@ricsam/r5d-worker 0.0.136 → 0.0.138

package/dist/types/runtime/storage.d.ts

@@ -0,0 +1,21 @@
+import { Database } from "bun:sqlite";
+import { type RunReceipt } from "./protocol";
+export declare function privateDirectory(path: string): void;
+export declare function readPrivateJson(path: string): unknown;
+/** Single host authority: a separate rollback-mode SQLite exclusive lock survives no process death. */
+export declare class ExecutorStore {
+    readonly root: string;
+    readonly db: Database;
+    private readonly lock;
+    constructor(root: string, installationId: string, workerId: string);
+    all(): RunReceipt[];
+    get(id: string): RunReceipt | null;
+    put(receipt: RunReceipt): void;
+    outputPath(id: string, stream: "stdout" | "stderr"): string;
+    append(id: string, stream: "stdout" | "stderr", data: Buffer): void;
+    read(id: string, stream: "stdout" | "stderr", offset: number, end: number, max: number): {
+        base64: string;
+        nextOffset: number;
+    };
+    close(): void;
+}

package/dist/types/runtime/test-harness.d.ts

@@ -0,0 +1,53 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { HostExecutorClient } from "./client";
+import { type ExecutorCommand, type ExecutorConfig } from "./protocol";
+import type { OperationEnvelope, OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
+export declare const testEnvironment: {
+    PATH: string;
+    HOME: string;
+    LANG: string;
+};
+export declare const delay: (ms: number) => Promise<void>;
+export declare function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs?: number): Promise<T>;
+export declare function stop(child: ChildProcessWithoutNullStreams, signal?: NodeJS.Signals): Promise<void>;
+export declare class AdapterProcess {
+    readonly process: ChildProcessWithoutNullStreams;
+    private pending;
+    constructor(configPath: string);
+    request<T = {
+        state: string;
+    }>(command: ExecutorCommand): Promise<T>;
+}
+export declare class Harness {
+    readonly root: string;
+    readonly cwd: string;
+    readonly stateDir: string;
+    readonly daemonPath: string;
+    readonly tokens: {
+        [k: string]: string;
+    };
+    readonly config: ExecutorConfig;
+    readonly clients: Record<string, HostExecutorClient>;
+    readonly adapterPaths: Record<string, string>;
+    readonly adapters: AdapterProcess[];
+    daemon?: ChildProcessWithoutNullStreams;
+    constructor(options?: Partial<ExecutorConfig>);
+    startDaemon(): Promise<void>;
+    adapter(id: "blue" | "green" | "third"): AdapterProcess;
+    fence(ownerId?: string, epoch?: number): OwnershipFence;
+    promote(ownerId?: string, epoch?: number, leaseMs?: number): Promise<unknown>;
+    operation(operationId?: string, argv?: string[], ownerId?: string, epoch?: number): OperationEnvelope;
+    run(operationId: string, ownerId?: string, epoch?: number): {
+        operationId: string;
+        userId: string;
+        sessionId: string;
+        fence: {
+            installationId: string;
+            resourceType: string;
+            resourceId: string;
+            ownerId: string;
+            epoch: number;
+        };
+    };
+    close(): Promise<void>;
+}

package/dist/types/runtime/workspace/artifacts.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { type WorkspaceIdentity } from "./contracts";
+export declare const SessionArtifactChunk: z.ZodObject<{
+    method: z.ZodLiteral<"materializeArtifact">;
+    id: z.ZodString;
+    filename: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    offset: z.ZodNumber;
+    base64: z.ZodString;
+    seal: z.ZodBoolean;
+}, z.core.$strict>;
+export type SessionArtifactChunk = z.infer<typeof SessionArtifactChunk>;
+export declare const RESERVED_ARTIFACT_ENV: readonly ["R5D_ROOT", "R5D_SESSION_ID"];
+/** Session artifacts never join repository snapshots or another session's env. */
+export declare class SessionArtifactStore {
+    readonly authorityRoot: string;
+    constructor(authorityRoot: string);
+    environment(identity: WorkspaceIdentity): Promise<{
+        R5D_ROOT: string;
+        R5D_SESSION_ID: string;
+    }>;
+    materialize(identity: WorkspaceIdentity, input: SessionArtifactChunk): Promise<{
+        filename: string;
+        sha256: string;
+        size: number;
+        nextOffset: number;
+        complete: boolean;
+    }>;
+}

package/dist/types/runtime/workspace/authority.d.ts

@@ -0,0 +1,338 @@
+import { OperationEnvelope } from "@ricsam/r5d-api/runtime-protocol";
+import { type PollResult, type RunIdentity } from "../protocol";
+import { WorkspaceConfig, type ExecutorRoute, type WorkspaceIdentity, type ApprovedWorkbench as ApprovedWorkbenchInput } from "./contracts";
+import { SessionArtifactChunk } from "./artifacts";
+import { WorkspaceFileWrite } from "./file-write";
+import { WorkspaceStorageClient } from "./storage-client";
+export interface WorkspaceAuthorityOptions {
+    config: WorkspaceConfig;
+    storage: (identity: WorkspaceIdentity) => Promise<WorkspaceStorageClient>;
+    executor: (identity: WorkspaceIdentity) => Promise<ExecutorRoute>;
+    /** Trusted catalog authorization; never a client-supplied filesystem path. */
+    resolveWorkbench?: (identity: WorkspaceIdentity) => Promise<ApprovedWorkbenchInput | null>;
+}
+/** Independent resource owner. Gate and workbench never live in replaceable adapters/gateways.
+ * Private root is exclusively owned; a crash leaves lock+intent for explicit maintenance.
+ */
+export declare class WorkspaceAuthority {
+    private readonly options;
+    readonly config: ReturnType<typeof WorkspaceConfig.parse>;
+    private readonly benches;
+    private readonly queues;
+    private readonly lockId;
+    private closing;
+    private closed;
+    private closeTask?;
+    private readonly actions;
+    private pending;
+    private constructor();
+    static open(options: WorkspaceAuthorityOptions): Promise<WorkspaceAuthority>;
+    private readonly registrations;
+    private bench;
+    private readonly hydrations;
+    ensureHydrated(identity: WorkspaceIdentity): Promise<void>;
+    readFile(identity: WorkspaceIdentity, file: string): Promise<{
+        path: string;
+        content: string;
+        bytes: number;
+    }>;
+    processes(identity: WorkspaceIdentity): Promise<{
+        workerLabel: string;
+        operationId: string;
+        userId: string;
+        sessionId: string | null;
+        payloadHash: string;
+        state: "accepted" | "running" | "completed" | "cancelled" | "unknown";
+        pid: number | null;
+        pty: boolean;
+        lane: import("zod").infer<typeof import("../protocol").Lane>;
+        stdoutBytes: number;
+        stderrBytes: number;
+        stdinClosed: boolean;
+        exitCode: number | null;
+        signal: string | null;
+        reason: string | null;
+        artifactEnvironment?: boolean;
+        mutating: boolean;
+        argv?: string[];
+        cwd?: string;
+        startedAt?: string;
+        updatedAt?: string;
+        completedAt?: string;
+    }[]>;
+    fileHistoryDates(identity: WorkspaceIdentity, file: string): Promise<{
+        createdAt: string | null;
+        updatedAt: string;
+    }>;
+    /** Bounded file browsing through the same catalog-authorized workbench as tools. */
+    inspectFiles(identity: WorkspaceIdentity, command: {
+        method: "directory" | "raw";
+        path: string;
+    }): Promise<{
+        path: string;
+        base64: string;
+        size: number;
+        modifiedAt: string;
+        directory?: undefined;
+        entries?: undefined;
+    } | {
+        directory: string;
+        entries: {
+            name: string;
+            path: string;
+            type: string;
+            size: number | null;
+            modifiedAt: string;
+        }[];
+        path?: undefined;
+        base64?: undefined;
+        size?: undefined;
+        modifiedAt?: undefined;
+    }>;
+    inspectGit(identity: WorkspaceIdentity, command: {
+        method: "status" | "diff" | "history" | "fileDiff";
+        path?: string;
+        base?: string;
+    }): Promise<{
+        head: string;
+        treeHash: string;
+        commits: {
+            hash: string | undefined;
+            parents: string[];
+            subject: string | undefined;
+            authorName: string | undefined;
+            authorEmail: string | undefined;
+            authoredAt: string | undefined;
+            committedAt: string | undefined;
+        }[];
+        original?: undefined;
+        modified?: undefined;
+    } | {
+        head: string;
+        treeHash: string;
+        original: {
+            kind: string;
+            objectType: null;
+            mode: null;
+            byteSize: null;
+            content: null;
+        } | {
+            kind: string;
+            objectType: string | undefined;
+            mode: string | undefined;
+            byteSize: null;
+            content: null;
+        } | {
+            kind: string;
+            objectType: string;
+            mode: string | undefined;
+            byteSize: number;
+            content: string | null;
+        };
+        modified: {
+            kind: string;
+            objectType: null;
+            mode: null;
+            byteSize: null;
+            content: null;
+        } | {
+            kind: string;
+            objectType: string | undefined;
+            mode: string | undefined;
+            byteSize: null;
+            content: null;
+        } | {
+            kind: string;
+            objectType: string;
+            mode: string | undefined;
+            byteSize: number;
+            content: string | null;
+        };
+        commits?: undefined;
+    } | {
+        patch?: string | undefined;
+        head: string;
+        treeHash: string;
+        files: {
+            path: string;
+            status: string;
+            additions: number | null;
+            deletions: number | null;
+            binary: boolean;
+        }[];
+        commits?: undefined;
+        original?: undefined;
+        modified?: undefined;
+    }>;
+    private save;
+    private owned;
+    private serial;
+    private route;
+    private storage;
+    private refresh;
+    private idle;
+    status(identity: WorkspaceIdentity): Promise<{
+        files: string[] | null;
+        initialized: boolean;
+        head: string | null;
+        publishedMetadata?: {
+            head: string;
+            indexHash: string;
+        };
+        blocked: null | {
+            code: string;
+            message: string;
+            operationId?: string;
+            commit?: string;
+        };
+        runs: Record<string, {
+            sessionId?: string;
+            artifactEnvironment?: boolean;
+            mutating: boolean;
+            payloadHash: string;
+            state: string;
+            argv?: string[];
+            cwd?: string;
+            startedAt?: string;
+            updatedAt?: string;
+            completedAt?: string;
+        }>;
+        workbench: {
+            id: string;
+            userId: string;
+            sessionId: string;
+            repositoryId: string;
+            branch: string;
+            cwd: string;
+            nonmutatingArgv: string[][];
+            sharedSessionId?: string | undefined;
+        };
+    }>;
+    private cleanRefreshBase;
+    /** No-argument hydration is initial-only. Explicit expectedBase permits a clean,
+     * idle workbench refresh; all replaced source/index/ref bytes are retained. */
+    hydrate(identity: WorkspaceIdentity, expectedBase?: string): Promise<{
+        head: string;
+    }>;
+    private hydrateIdle;
+    private assertFreshAccountWorkbench;
+    private initializeAccountCanonical;
+    private replaceFile;
+    /** Explicit trusted import boundary for the first isolated README seed, not legacy tree import. */
+    seedReadme(identity: WorkspaceIdentity, readme: string): Promise<{
+        head: string;
+        unchanged?: boolean;
+    }>;
+    private installGitPolicy;
+    /** Scoped receipt lookup never repeats a file effect; completion can clear its own crash marker. */
+    fileWriteResult(identity: WorkspaceIdentity, input: {
+        id: string;
+    }): Promise<{
+        state: "absent";
+        result?: undefined;
+    } | {
+        state: "completed";
+        result: any;
+    }>;
+    fileWrite(identity: WorkspaceIdentity, raw: WorkspaceFileWrite): Promise<{
+        intentHash?: string | undefined;
+        method: string;
+        id: string;
+        userId: string;
+        sessionId: string;
+        path: string;
+        sha256: string;
+        gitBlobHash: string;
+        size: number;
+        modifiedAt: string;
+        requestHash: string;
+    }>;
+    private productAction;
+    private validateGithubRemote;
+    /** Import only a selected exact GitHub tree into canonical storage; never execute its Git configuration. */
+    importRepository(identity: WorkspaceIdentity, input: {
+        id: string;
+        url: string;
+        token: string;
+        defaultBranch: string;
+    }): Promise<{
+        head: string;
+        workspaceHead: string;
+    }>;
+    cloneBranch(identity: WorkspaceIdentity, sourceIdentity: WorkspaceIdentity, input: {
+        id: string;
+        workingTree: "carry" | "clean";
+    }): Promise<any>;
+    private importCommit;
+    commit(identity: WorkspaceIdentity, input: {
+        id: string;
+        expectedHead?: string;
+        message: string;
+    }): Promise<{
+        treeHash: string;
+        head: string;
+        unchanged?: boolean;
+    }>;
+    push(identity: WorkspaceIdentity, input: {
+        id: string;
+        expectedHead?: string;
+        remote: {
+            url: string;
+            token: string;
+            branch: string;
+            expectedHead?: string | null;
+        };
+    }): Promise<{
+        head: string | null;
+        pushed: boolean;
+    }>;
+    archiveBranch(identity: WorkspaceIdentity, input: {
+        id: string;
+    }): Promise<{
+        removed: boolean;
+        receipt: unknown;
+    }>;
+    /** An explicit user reset retains the complete old tree/index before hydration. */
+    reset(identity: WorkspaceIdentity, input: {
+        id: string;
+        expectedHead?: string | null;
+    }): Promise<{
+        reset: boolean;
+        retained: boolean;
+        head: string;
+    }>;
+    publish(identity: WorkspaceIdentity): Promise<{
+        head: string;
+        unchanged?: boolean;
+    }>;
+    private publishIdle;
+    /** Read-only resolution of a lost publication ACK; no mutation retry, rebase, reset, or file overwrite. */
+    reconcilePublication(identity: WorkspaceIdentity): Promise<{
+        head: string;
+    }>;
+    /** Resolve mutable account settings once, before the first terminal admission.
+     * A lost ACK must recover the same command and credential generations even if
+     * settings change before redelivery or the workspace service restarts. */
+    startWithCredentials(identity: WorkspaceIdentity, input: OperationEnvelope, resolve: () => Promise<Array<{
+        id: string;
+        generation: number;
+    }>>): Promise<import("..").RunReceipt>;
+    materializeArtifact(identity: WorkspaceIdentity, input: SessionArtifactChunk): Promise<{
+        filename: string;
+        sha256: string;
+        size: number;
+        nextOffset: number;
+        complete: boolean;
+    }>;
+    /** Default arbitrary shell is mutating. Exact trusted config approval is the sole exemption. */
+    start(identity: WorkspaceIdentity, input: OperationEnvelope): Promise<import("..").RunReceipt>;
+    private runRoute;
+    private action;
+    poll(identity: WorkspaceIdentity, run: RunIdentity, stdoutOffset?: number, stderrOffset?: number, maxBytes?: number): Promise<PollResult>;
+    private actionOutcome;
+    write(identity: WorkspaceIdentity, run: RunIdentity, actionId: string, data: string, eof?: boolean): Promise<import("..").ActionReceipt>;
+    resize(identity: WorkspaceIdentity, run: RunIdentity, actionId: string, cols: number, rows: number): Promise<import("..").ActionReceipt>;
+    cancel(identity: WorkspaceIdentity, run: RunIdentity, actionId: string): Promise<import("..").ActionReceipt>;
+    close(): Promise<void>;
+    private finishClose;
+}

package/dist/types/runtime/workspace/contracts.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import type { HostExecutorClient } from "../client";
+import type { OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
+export declare const ApprovedWorkbench: z.ZodObject<{
+    id: z.ZodString;
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    sharedSessionId: z.ZodOptional<z.ZodString>;
+    repositoryId: z.ZodString;
+    branch: z.ZodString;
+    cwd: z.ZodString;
+    nonmutatingArgv: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+export type ApprovedWorkbench = z.input<typeof ApprovedWorkbench>;
+export declare const WorkspaceConfig: z.ZodObject<{
+    installationId: z.ZodString;
+    root: z.ZodString;
+    workbenches: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodString;
+        sharedSessionId: z.ZodOptional<z.ZodString>;
+        repositoryId: z.ZodString;
+        branch: z.ZodString;
+        cwd: z.ZodString;
+        nonmutatingArgv: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+    dynamicWorkbenches: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type WorkspaceConfig = z.input<typeof WorkspaceConfig>;
+export type ExecutorRoute = {
+    client: Pick<HostExecutorClient, "start" | "poll" | "write" | "cancel"> & Partial<Pick<HostExecutorClient, "resize">>;
+    workerFence: OwnershipFence;
+};
+export type WorkspaceIdentity = {
+    userId: string;
+    sessionId: string;
+};
+export declare class WorkspaceError extends Error {
+    readonly code: string;
+    readonly rejectedBeforeAdmission: boolean;
+    constructor(code: string, message: string, rejectedBeforeAdmission?: boolean);
+}
+/** Constructed only by the authority before it admits publication work. */
+export declare class WorkspacePublicationNotAdmitted extends WorkspaceError {
+}
+export type WorkspacePublishResult = {
+    head: string;
+    unchanged?: boolean;
+    rejectedBeforeAdmission?: never;
+} | {
+    state: "rejected";
+    code: "capacity_busy";
+    rejectedBeforeAdmission: true;
+    message: string;
+    head?: never;
+    unchanged?: never;
+};
+export type WorkspaceState = {
+    initialized: boolean;
+    head: string | null;
+    /** Unchanged checkout metadata retained by automatic canonical publication. */
+    publishedMetadata?: {
+        head: string;
+        indexHash: string;
+    };
+    blocked: null | {
+        code: string;
+        message: string;
+        operationId?: string;
+        commit?: string;
+    };
+    runs: Record<string, {
+        sessionId?: string;
+        artifactEnvironment?: boolean;
+        mutating: boolean;
+        payloadHash: string;
+        state: string;
+        argv?: string[];
+        cwd?: string;
+        startedAt?: string;
+        updatedAt?: string;
+        completedAt?: string;
+    }>;
+};
+export declare const DEFAULT_WORKSPACE_IGNORE = "# Required destination workbench exclusions; keep these rules effective.\n.env\n.env.*\n!.env.example\nnode_modules/\n.r5d/\n.r5d-next/\n.ssh/\n.kube/\nsecrets/\ncredentials/\n.next/\ndist/\nbuild/\ncoverage/\n.cache/\n*.pem\n*.key\n";

package/dist/types/runtime/workspace/file-write.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const WorkspaceFileWrite: z.ZodObject<{
+    method: z.ZodLiteral<"fileWrite">;
+    id: z.ZodString;
+    path: z.ZodString;
+    expectedSha256: z.ZodNullable<z.ZodString>;
+    intentHash: z.ZodOptional<z.ZodString>;
+    base64: z.ZodString;
+}, z.core.$strict>;
+export type WorkspaceFileWrite = z.infer<typeof WorkspaceFileWrite>;
+export declare const WorkspaceFileWriteLookup: z.ZodObject<{
+    method: z.ZodLiteral<"fileWriteResult">;
+    id: z.ZodString;
+}, z.core.$strict>;

package/dist/types/runtime/workspace/files.d.ts

@@ -0,0 +1,21 @@
+export declare const sha256: (bytes: Buffer | string) => string;
+export declare function privateRoot(root: string, installationId: string): Promise<void>;
+export declare function noSymlinkAncestors(file: string): Promise<void>;
+export declare function readRegular(file: string, limit?: number): Promise<Buffer>;
+export declare function durableJson(file: string, value: unknown): Promise<void>;
+/** All Git operates in authority-created repos; NEVER workbench .git/config/index.
+ * hash-object --no-filters and update-index --index-info replace git add/checkout.
+ */
+export declare function git(cwd: string, args: string[], input?: Buffer | string, indexFile?: string, transport?: {
+    token: string;
+}): Promise<Buffer>;
+export declare function sourcePath(file: string): void;
+export declare function sourceBytes(bytes: Buffer, file?: string): void;
+export type TreeEntry = {
+    file: string;
+    mode: string;
+    oid: string;
+};
+export declare function selectedTree(repo: string, commit: string): Promise<TreeEntry[]>;
+export declare function verifyIgnore(repo: string, cwd: string): Promise<void>;
+export declare function snapshotTree(repo: string, cwd: string, canonicalHead?: string | null): Promise<string>;

package/dist/types/runtime/workspace/http-body.d.ts

@@ -0,0 +1,9 @@
+/** Byte-bounded streaming reader. The deadline covers reading only, never downstream effects.
+ * Cancellation is best effort and is deliberately NOT awaited: a poisoned underlying
+ * source may return a cancellation promise that never settles.
+ */
+export declare class BodyReadError extends Error {
+    readonly code: "body_too_large" | "body_timeout" | "body_missing";
+    constructor(code: "body_too_large" | "body_timeout" | "body_missing");
+}
+export declare function readBoundedBody(body: ReadableStream<Uint8Array> | null, limit: number, timeoutMs: number): Promise<Buffer>;

package/dist/types/runtime/workspace/storage-client.d.ts

@@ -0,0 +1,23 @@
+import { OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
+import { StorageRequest, type StorageMutation } from "./storage-wire";
+export type StorageTransport = (request: StorageRequest) => Promise<unknown>;
+type MutationInput = StorageMutation extends infer T ? (T extends StorageMutation ? Omit<T, "fence" | "callerFence"> : never) : never;
+/** The token provider must issue installation/user/subject/exact storageCallerScope grants.
+ * HTTPS deployments inject a fetch implementation with private mTLS, never disable verification.
+ * Transport failures are unknown delivery. This client NEVER automatically retries a mutation. */
+export declare class WorkspaceStorageClient {
+    readonly installationId: string;
+    private readonly transport;
+    private readonly caller;
+    constructor(installationId: string, transport: StorageTransport, caller: () => Promise<OwnershipFence>);
+    static http(options: {
+        installationId: string;
+        url: string;
+        token: (request: StorageRequest) => Promise<string>;
+        caller: () => Promise<OwnershipFence>;
+        fetch?: typeof fetch;
+    }): WorkspaceStorageClient;
+    read<T>(request: Exclude<StorageRequest, StorageMutation>): Promise<T>;
+    mutate<T>(input: MutationInput): Promise<T>;
+}
+export {};