engineering-behavior-observatory 0.2.1

package/dist/src/workspaces.d.ts

@@ -0,0 +1,56 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type Digest } from "./contracts.js";
+/**
+ * Process primitives owned by one setup invocation. Child processes started
+ * here are placed in a private process group and reaped before setup returns.
+ */
+export type WorkspaceSetupContext = {
+    spawn: (command: string, args?: readonly string[], options?: SpawnOptions) => ChildProcess;
+};
+export type WorkspaceSetupStep = (workspacePath: string, context: WorkspaceSetupContext) => void | Promise<void>;
+export type WorkspaceMaterializationOptions = {
+    bundleRoot: string;
+    packetLocator: string;
+    attemptId?: string;
+    workspaceParent?: string;
+    /** Alias for workspaceParent retained for callers that name the base directory a root. */
+    workspaceRoot?: string;
+    freezeLocator?: string;
+    retainOnFailure?: boolean;
+    setup?: WorkspaceSetupStep | readonly WorkspaceSetupStep[];
+    setupSteps?: readonly WorkspaceSetupStep[];
+};
+export type WorkspaceMaterialization = {
+    attemptId: string;
+    packetId: string;
+    packetDigest: Digest;
+    fixtureDigest: Digest;
+    /** The digest declared by the frozen fixture, before any harness execution. */
+    startingDigest: Digest;
+    workspacePath: string;
+    /** Alias for workspacePath for callers that use path-oriented lifecycle code. */
+    path: string;
+    workspaceFingerprint: string | null;
+    /** Alias for workspaceFingerprint used by workspace evidence callers. */
+    workspaceDigest: string | null;
+    workspaceIdentity?: WorkspaceIdentity;
+    status: "ready" | "failed" | "cleaned";
+    state: "ready" | "failed" | "cleaned";
+    retainOnFailure: boolean;
+    retained: boolean;
+    workspaceRemoved: boolean;
+    error?: string;
+    cleanup: (outcome?: "success" | "failure") => Promise<void>;
+};
+/**
+ * Materialize one admitted, frozen task packet into an isolated attempt path.
+ * Only selected regular files and directories from the verified archive enter
+ * the workspace; restricted packet components never do.
+ */
+export declare function materializeWorkspace(options: WorkspaceMaterializationOptions): Promise<WorkspaceMaterialization>;
+export declare function cleanupWorkspace(materialization: WorkspaceMaterialization, outcome?: "success" | "failure"): Promise<void>;
+type WorkspaceIdentity = {
+    dev: number;
+    ino: number;
+};
+export {};