feat(ql3): establish 3.0 incubation baseline

2026-09-20 16:07:11 +08:00 · 2026-08-12 00:25:26 +08:00
parent 4bf92dcfeb
commit c699c32461
2817 changed files with 779642 additions and 653 deletions
@@ -0,0 +1,154 @@
+export const EXECUTOR_TYPES = [
+  'local_process',
+  'docker',
+  'kubernetes',
+  'remote_worker',
+] as const;
+
+export type ExecutorType = (typeof EXECUTOR_TYPES)[number];
+
+export type ExecutionCommand =
+  | {
+      kind: 'argv';
+      file: string;
+      args: readonly string[];
+    }
+  | {
+      kind: 'shell';
+      command: string;
+      shell?: string;
+    };
+
+export type ExecutionLimitEnforcement = 'required' | 'best_effort';
+
+export interface ExecutionNumericLimit {
+  value: number;
+  enforcement: ExecutionLimitEnforcement;
+}
+
+export interface ExecutionResourcePolicy {
+  memoryBytes?: ExecutionNumericLimit;
+  cpuMillisPerSecond?: ExecutionNumericLimit;
+  filesystemIsolation?: ExecutionLimitEnforcement;
+  networkIsolation?: ExecutionLimitEnforcement;
+}
+
+export interface ExecutionSpec {
+  runId: string;
+  attemptId: string;
+  projectId: string;
+  taskId: string;
+  taskRevision: string;
+  command: ExecutionCommand;
+  workingDirectory?: string;
+  environmentPolicy: 'inherit' | 'isolated';
+  timeoutMs?: number;
+  terminationGraceMs: number;
+  resourcePolicy?: ExecutionResourcePolicy;
+}
+
+export type ExecutionOutputStream = 'stdout' | 'stderr';
+
+export interface ExecutionOutputChunk {
+  stream: ExecutionOutputStream;
+  chunk: Uint8Array;
+  observedAtMs: number;
+}
+
+export interface ExecutionOutputSink {
+  write(output: ExecutionOutputChunk): Promise<void>;
+}
+
+export interface ExecutionAbortSignal {
+  readonly aborted: boolean;
+  addEventListener?: (
+    type: 'abort',
+    listener: () => void,
+    options?: { once?: boolean },
+  ) => void;
+  removeEventListener?: (type: 'abort', listener: () => void) => void;
+}
+
+export interface ExecutionContext {
+  environment: Readonly<Record<string, string>>;
+  signal?: ExecutionAbortSignal;
+  output: ExecutionOutputSink;
+  /** Ephemeral capability for the durable completion launcher; never persist raw. */
+  completionCallback?: {
+    token: string;
+    callbackSequence: number;
+  };
+}
+
+export type ExecutionOutcome =
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'timed_out'
+  | 'lost';
+
+export interface ExecutionDiagnostic {
+  code: string;
+  summary: string;
+}
+
+export interface ExecutionResult {
+  outcome: ExecutionOutcome;
+  startedAtMs: number;
+  finishedAtMs: number;
+  exitCode?: number;
+  signal?: NodeJS.Signals;
+  errorCode?: string;
+  errorSummary?: string;
+  diagnostics?: readonly ExecutionDiagnostic[];
+}
+
+export interface ExecutionHandle {
+  id: string;
+  /** Opaque, bounded identity used to verify ownership after a process restart. */
+  durableHandle?: string;
+  executorType: ExecutorType;
+  runId: string;
+  attemptId: string;
+  startedAtMs: number;
+  pid?: number;
+  completion: Promise<ExecutionResult>;
+}
+
+export type ExecutionStopKind =
+  | 'user'
+  | 'policy'
+  | 'shutdown'
+  | 'reconcile'
+  | 'timeout';
+
+export interface ExecutionStopReason {
+  kind: ExecutionStopKind;
+  requestedAtMs: number;
+}
+
+export interface ExecutionStopResult {
+  status: 'already_exited' | 'termination_requested';
+  termSignalSent: boolean;
+  killSignalSent: boolean;
+}
+
+export type ExecutionInspectionStatus = 'running' | 'stopping' | 'exited';
+
+export interface ExecutionInspection {
+  status: ExecutionInspectionStatus;
+  result?: ExecutionResult;
+}
+
+export type ExecutorCapabilityLevel = 'none' | 'best_effort' | 'enforced';
+
+export interface ExecutorCapabilities {
+  timeout: boolean;
+  processGroupTermination: boolean;
+  workingDirectory: boolean;
+  isolatedEnvironment: boolean;
+  memoryLimit: ExecutorCapabilityLevel;
+  cpuLimit: ExecutorCapabilityLevel;
+  filesystemIsolation: ExecutorCapabilityLevel;
+  networkIsolation: ExecutorCapabilityLevel;
+}