@opengeni/runtime 3.0.1 → 4.0.0-canary.35585322809001

package/src/sandbox/materialization-verification-error.ts

@@ -0,0 +1,65 @@
+export type MaterializationFailureReason =
+  | "path_not_visible"
+  | "command_failed"
+  | "command_pending"
+  | "invalid_response"
+  | "command_error";
+
+/** Exact diagnostics belong only in authenticated durable session events.
+ * Metrics receive the closed reason vocabulary, never paths or provider output. */
+export type MaterializationVerificationDiagnostic = {
+  reason: MaterializationFailureReason;
+  path: string;
+  workdir: string;
+  command: string;
+  output: string | null;
+  exitCode: number | null;
+  providerSessionId: number | null;
+  /** Exact ephemeral read-only probe identity, never a retained command alias. */
+  providerExecution?: { sandboxId: string; taskId: string; execId: string };
+  causeMessage?: string;
+};
+
+const EXPLANATIONS: Record<MaterializationFailureReason, string> = {
+  path_not_visible: "the provider could not see the destination path",
+  command_failed: "the visibility-check command exited unsuccessfully",
+  command_pending: "the visibility-check command was still running; path visibility is unconfirmed",
+  invalid_response: "the visibility check returned no valid success confirmation",
+  command_error: "the provider could not complete the visibility-check command",
+};
+
+export class SandboxMaterializationVerificationError extends Error {
+  readonly code = "sandbox_materialization_verification_failed";
+
+  constructor(
+    readonly diagnostic: MaterializationVerificationDiagnostic,
+    options?: ErrorOptions,
+  ) {
+    super(
+      `Sandbox materialization verification failed: ${EXPLANATIONS[diagnostic.reason]}: ${diagnostic.path}`,
+      options,
+    );
+    this.name = "SandboxMaterializationVerificationError";
+  }
+}
+
+const providerDiagnostics = new WeakMap<object, MaterializationVerificationDiagnostic>();
+
+/** Keep cancellation, route-loss, and provider retry identities unchanged. */
+export function retainMaterializationVerificationDiagnostic(
+  error: unknown,
+  diagnostic: MaterializationVerificationDiagnostic,
+): void {
+  if (error !== null && (typeof error === "object" || typeof error === "function")) {
+    providerDiagnostics.set(error, diagnostic);
+  }
+}
+
+export function materializationVerificationDiagnostic(
+  error: unknown,
+): MaterializationVerificationDiagnostic | undefined {
+  if (error instanceof SandboxMaterializationVerificationError) return error.diagnostic;
+  return error !== null && (typeof error === "object" || typeof error === "function")
+    ? providerDiagnostics.get(error)
+    : undefined;
+}

package/src/sandbox/provider-command-session.ts

@@ -1,8 +1,14 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SandboxProviderCommand } from "@opengeni/contracts";
+import type {
+  SandboxProviderCommand,
+  ModalRouterProviderCommand,
+  CommandSupervisionReceipt,
+} from "@opengeni/contracts";
 
 export type ProviderCommandOutput = {
   command: SandboxProviderCommand;
+  /** Exact read baseline for atomic byte-offset capture; absent for legacy pages. */
+  expected?: ModalRouterProviderCommand;
   chunks: Array<{ stream: "stdout" | "stderr"; chunkId: string; text: string }>;
   exitCode: number | null;
   streamFidelity?: "separate" | "merged";
@@ -11,12 +17,36 @@ export type ProviderCommandOutput = {
 /** These callbacks are supplied by the control plane after exact-route
  * retention/adoption. They are never accepted as command arguments. */
 export type ProviderCommandPersistence = {
+  rejectSupervisedLaunch?(command: ModalRouterProviderCommand): Promise<void>;
   load(): Promise<SandboxProviderCommand | null>;
   acknowledge(command: SandboxProviderCommand): Promise<SandboxProviderCommand>;
-  reserveInput(): Promise<number>;
+  reserveInput(byteLength?: number): Promise<number>;
+  recordSupervisionReceipt?(receipt: CommandSupervisionReceipt): Promise<void>;
+  loadSupervisionReceipt?(): Promise<CommandSupervisionReceipt | null>;
+  requestCancellation?(reason: "provider_deadline" | "explicit_stop"): Promise<void>;
+  cancellationRequested?(): Promise<boolean>;
+  captureRouterPage?(page: {
+    expected: ModalRouterProviderCommand;
+    command: ModalRouterProviderCommand;
+    stdout: string;
+    stderr: string;
+  }): Promise<{ command: ModalRouterProviderCommand; captured: boolean }>;
 };
 
+export class ProviderCommandStartRejectedError extends Error {
+  constructor(cause: unknown) {
+    super("Provider rejected command before start", { cause });
+    this.name = "ProviderCommandStartRejectedError";
+  }
+}
+
 export type ProviderCommandSession = {
+  verifyCommandSupervisionCapability?(): Promise<{ sandboxId: string; taskId: string }>;
+  releaseSupervisedCommand?(handle: number): Promise<void>;
+  cancelSupervisedCommand?(
+    handle: number,
+    reason: "provider_deadline" | "explicit_stop",
+  ): Promise<boolean>;
   /** Abort only starts/initial observations still owned by this session call. */
   cancelPendingExecCommand?(): Promise<void>;
   getProviderCommand?(handle: number): SandboxProviderCommand | null;
@@ -27,9 +57,47 @@ export type ProviderCommandSession = {
   ): void;
   getProviderCommandOutput?(result: unknown): ProviderCommandOutput | null;
   acknowledgeCommandOutput?(result: string): Promise<void>;
+  /** Returns false for a legacy receipt. True means bytes and offsets committed
+   * together (or the page lost a cursor CAS and was safely discarded). */
+  captureCommandOutput?(result: string): Promise<boolean>;
 };
 
 const admission = new AsyncLocalStorage<number>();
+export type PendingCommandSupervision = { managed: boolean };
+const pendingSupervision = new AsyncLocalStorage<PendingCommandSupervision>();
+export function withPendingCommandSupervision<T>(
+  state: PendingCommandSupervision | undefined,
+  fn: () => T,
+): T {
+  return state ? pendingSupervision.run(state, fn) : fn();
+}
+/** Called only by the provider adapter before dispatching an idle supervisor. */
+export function markPendingCommandSupervised(): void {
+  const state = pendingSupervision.getStore();
+  if (state) state.managed = true;
+}
+const supervisionReady = new AsyncLocalStorage<boolean>();
+type SupervisedLaunchReservation = {
+  reserve(command: ModalRouterProviderCommand): Promise<void>;
+};
+const supervisedLaunch = new AsyncLocalStorage<SupervisedLaunchReservation>();
+export function withSupervisedLaunchReservation<T>(
+  reservation: SupervisedLaunchReservation,
+  fn: () => T,
+): T {
+  return supervisedLaunch.run(reservation, fn);
+}
+export async function reserveSupervisedLaunch(command: ModalRouterProviderCommand): Promise<void> {
+  const reservation = supervisedLaunch.getStore();
+  if (!reservation) throw new Error("Supervised launch requires durable pre-dispatch reservation");
+  await reservation.reserve(command);
+}
+export function withCommandSupervisionReady<T>(ready: boolean, fn: () => T): T {
+  return supervisionReady.run(ready, fn);
+}
+export function admittedCommandSupervisionReady(): boolean {
+  return supervisionReady.getStore() === true;
+}
 export const MAX_PROVIDER_COMMAND_HANDLE = 2147483647;
 
 /** The alias is allocated by serialized workspace mutation admission, not by