@gfdelarue/testkit 0.3.0

package/dist/engines/playwright/runtime/sandbox.js

@@ -0,0 +1 @@
+import{expect as R,request as x,test as E}from"@playwright/test";import{readPlaywrightContext as p}from"./runtime-input.js";const c=String;export function createUiSandbox(e={}){const t=createSandboxId(e);return{expect:R,test:E.extend({testkitSandbox:async({page:r},n)=>{await n({id:t,backendBaseUrl:resolveBackendBaseUrl(e),frontendBaseUrl:resolveFrontendBaseUrl(e),page:r})}})}}export function createSandboxId(e={}){const t=c(e.prefix||"ui").replace(/[^A-Za-z0-9_-]+/gu,"-").replace(/^-+|-+$/gu,"")||"ui",r=process.env.TEST_WORKER_INDEX||process.env.TESTKIT_WORKER_INDEX||"0",n=process.env.TESTKIT_LEASE_ID||process.env.TESTKIT_RUNTIME_ID||process.pid;return`${t}-${String(n)}-${r}`}export function resolveFrontendBaseUrl(e={}){const t=l();return m(U(e.frontendBaseUrl,e.baseUrl,u(t,"frontendBaseUrl"),process.env.TESTKIT_FRONTEND_BASE_URL,process.env.BASE_URL),{allowRemote:e.allowRemote??u(t,"allowRemote")})}export function resolveBackendBaseUrl(e={}){const t=l();return m(U(e.backendBaseUrl,u(t,"backendBaseUrl"),process.env.TESTKIT_BACKEND_BASE_URL,process.env.API_BASE_URL),{allowRemote:e.allowRemote??u(t,"allowRemote")})}export function assertSafeUiTarget(e,t={}){const r=T(e);if(!r)throw new Error(`Invalid UI target URL: ${c(e)}`);if(b(t))return r.toString().replace(/\/$/u,"");if(!_(r.hostname))throw new Error(`UI target must be local unless allowRemote is true: ${c(e)}`);return r.toString().replace(/\/$/u,"")}export function assertSafeUiTargets(e=[],t={}){return e.map(r=>assertSafeUiTarget(r,t))}export async function createAuthedApiClient(e=x,t={}){const r=assertSafeUiTarget(resolveBackendBaseUrl(t),t);return e.newContext({baseURL:r,extraHTTPHeaders:t.headers||{}})}export async function waitForUiSettled(e,t={}){const r=t.timeout??5e3;await e.waitForLoadState("domcontentloaded",{timeout:r}),await waitForAnimationFrames(e,t.frames??2),await waitForNetworkIdle(e,{frames:t.frames??2,timeout:r})}export async function waitForAnimationFrames(e,t=2){const r=Math.max(1,Number(t)||1);await e.evaluate(n=>new Promise(i=>{let o=n;const a=()=>{if(o-=1,o<=0){i();return}requestAnimationFrame(a)};requestAnimationFrame(a)}),r)}export async function waitForNetworkIdle(e,t={}){const r=t.timeout??2e3;try{await e.waitForLoadState("networkidle",{timeout:r})}catch{await e.waitForLoadState("load",{timeout:r}).catch(()=>{}),await waitForAnimationFrames(e,t.frames??2)}}export async function waitForElementStable(e,t,r={}){const n=Math.max(1,Number(r.frames)||2),i=e.locator(t);await i.waitFor({state:"visible",timeout:r.timeout}),await i.evaluate(async(o,a)=>{let s=0,f=JSON.stringify(o.getBoundingClientRect().toJSON());for(;s<a;){await new Promise(g=>requestAnimationFrame(()=>{g()}));const d=JSON.stringify(o.getBoundingClientRect().toJSON());d===f?s+=1:s=0,f=d}},n)}export async function waitForImagesLoaded(e,t=null){const r=t?`${t} img`:"img",n=e.locator(r),i=await n.count();for(let o=0;o<i;o+=1)await n.nth(o).evaluate(a=>{if(!a.complete)return new Promise(s=>{a.addEventListener("load",s,{once:!0}),a.addEventListener("error",s,{once:!0})})})}function m(e,t={}){const r=c(e||"").trim();if(!r)throw new Error("A UI base URL is required");return assertSafeUiTarget(r,t)}function l(){const e=p()?.uiConfig;return S(e)?e:{}}function T(e){try{return new URL(c(e))}catch{return null}}function b(e={}){if(w(e.allowRemote))return!0;const t=l();return w(u(t,"allowRemote"))}function w(e){return e===!0||e==="true"}function _(e){return e==="localhost"||e==="127.0.0.1"||e==="::1"||e.endsWith(".localhost")}function u(e,t){return S(e)?Reflect.get(e,t):void 0}function U(...e){return e.find(Boolean)}function S(e){return typeof e=="object"&&e!==null}

package/dist/engines/runtime-input-file.d.ts

@@ -0,0 +1,25 @@
+export declare const ownedRuntimeInputModuleUrl: string;
+export declare const RUNTIME_INPUT_BYTE_MEASURE: {
+    unitLabel: string;
+    unitsOf: (text: string) => number;
+};
+/**
+ * Single-writer protocol for the files a host prepares inside an owned task
+ * directory and later hands to a guest process by pointer + digest. Writes are
+ * exclusive-create (0o600), fsynced, and atomically renamed into place; reads
+ * re-verify the file is still an owned regular file with the prepared size,
+ * owner-only permissions, identity realpath, and matching SHA-256 digest.
+ */
+export interface OwnedFileProtocol {
+    readonly filename: string;
+    readonly label: string;
+    readonly maxSizeBytes: number;
+}
+export interface OwnedFileRecord {
+    readonly directory: string;
+    readonly file: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
+export declare function writeOwnedRuntimeInput(taskDirectory: string, document: unknown, protocol: OwnedFileProtocol): Promise<OwnedFileRecord>;
+export declare function readVerifiedOwnedFile(record: OwnedFileRecord, protocol: OwnedFileProtocol): Promise<string>;

package/dist/engines/runtime-input-file.js

@@ -0,0 +1 @@
+import u from"node:crypto";import a from"node:fs/promises";import o from"node:path";import{serializeBoundedJson as c,RUNTIME_INPUT_JSON_BOUNDS as h}from"./contracts/json-bounds.js";import{readStableEvidenceFile as y,evidenceFileAccess as b}from"./adapters/evidence-files.js";export const ownedRuntimeInputModuleUrl=new URL("../../dist/engines/runtime-input-file.js",import.meta.url).href,RUNTIME_INPUT_BYTE_MEASURE={unitLabel:"bytes",unitsOf:t=>Buffer.byteLength(t,"utf8")};export async function writeOwnedRuntimeInput(t,e,i){const n=c(e,i.label,h,RUNTIME_INPUT_BYTE_MEASURE),s=await m(t,i.label),w=Buffer.byteLength(n);if(w>i.maxSizeBytes)throw new Error(`${i.label} exceeds the ${i.maxSizeBytes.toString()} byte limit`);const f=o.join(s,i.filename),l=o.join(s,`.${i.filename}.${process.pid.toString()}.${u.randomUUID()}.tmp`);let r=null;try{r=await a.open(l,"wx",384),await r.writeFile(n,"utf8"),await r.sync(),await r.close(),r=null,await a.rename(l,f),await a.chmod(f,384)}catch(d){throw await r?.close().catch(()=>{}),await a.rm(l,{force:!0}).catch(()=>{}),d}return{directory:s,file:f,sha256:u.createHash("sha256").update(n,"utf8").digest("hex"),sizeBytes:w}}export async function readVerifiedOwnedFile(t,e){const i=await m(t.directory,e.label);if(o.dirname(t.file)!==i)throw new Error(`${e.label} escaped its owned task directory`);const n=await a.lstat(t.file,{bigint:!0});if(!n.isFile()||n.isSymbolicLink())throw new Error(`${e.label} must be an owned regular file`);if(n.size!==BigInt(t.sizeBytes)||n.size>BigInt(e.maxSizeBytes))throw new Error(`${e.label} size changed after preparation`);if(process.platform!=="win32"&&(n.mode&63n)!==0n)throw new Error(`${e.label} permissions must be owner-only`);const s=await a.realpath(t.file);if(s!==t.file||o.dirname(s)!==i)throw new Error(`${e.label} resolved outside its owned task directory`);const{contents:w,sha256:f}=await y(s,e.maxSizeBytes,e.label,b,n),l=Buffer.from(t.sha256),r=Buffer.from(f);if(l.length!==r.length||!u.timingSafeEqual(r,l))throw new Error(`${e.label} integrity check failed`);return w.toString("utf8")}async function m(t,e){if(!o.isAbsolute(t))throw new Error(`${e} directory must be absolute`);const i=await a.realpath(t);if(!(await a.stat(i)).isDirectory())throw new Error(`${e} directory must be a directory`);return i}

package/dist/environment/lifecycle-artifacts.d.ts

@@ -0,0 +1,7 @@
+import type { RunManifest } from "../process/runs/manifest.js";
+interface ActiveRunIdsOptions {
+    activeRunIds?: ReadonlySet<string>;
+}
+export declare function reconcileInactiveRunArtifact(productDir: string, manifest: Readonly<RunManifest>): void;
+export declare function reconcileOrphanedLiveRunArtifact(productDir: string, { activeRunIds }?: Readonly<ActiveRunIdsOptions>): boolean;
+export {};

package/dist/environment/lifecycle-artifacts.js

@@ -0,0 +1 @@
+import o from"fs";import a from"path";import{finalizeLiveRunArtifact as i}from"../evidence/index.js";export function reconcileInactiveRunArtifact(t,n){typeof n.runId=="string"&&i(t,{runId:n.runId,reason:"stale run process not active",status:"interrupted"})}export function reconcileOrphanedLiveRunArtifact(t,{activeRunIds:n=new Set}={}){const r=c(t),e=r?.run.id||null;return!e||r?.run.status!=="running"||n.has(e)?!1:i(t,{runId:e,reason:"stale live artifact has no active run manifest",status:"interrupted"})}function c(t){try{const n=JSON.parse(o.readFileSync(a.join(t,".testkit","results","live.json"),"utf8"));return f(n)}catch{return null}}function f(t){if(!u(t)||!u(t.run))return null;const n=t.run.id,r=t.run.status;return!s(n)||!s(r)?null:{run:{id:n,status:r}}}function u(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function s(t){return t===void 0||typeof t=="string"}

package/dist/environment/lifecycle-controller.d.ts

@@ -0,0 +1,71 @@
+import type { SupervisedProcessHandle, SupervisedProcessReady } from "../process/index.js";
+import type { RuntimeInstanceContext } from "./runtime-contexts.js";
+import type { LocalServiceLifecycle } from "./services.js";
+import { type ProductLifecycleFence } from "../process/lifecycle-fence.js";
+import { type RunManifest, type RunManifestService } from "../process/runs/manifest.js";
+type LifecycleServiceConfig = Parameters<LocalServiceLifecycle["registerService"]>[0];
+export interface RunLifecycleOptions {
+    controller?: unknown;
+    heartbeat?: boolean;
+    keepAlive?: boolean;
+    pid?: number;
+    resetResultsBeforePublish?: boolean;
+    runId?: string;
+}
+export interface RunPortQuery {
+    host?: unknown;
+    port?: unknown;
+}
+export interface RunPortOwner {
+    active: boolean;
+    manifest: RunManifest;
+    service: RunManifestService;
+}
+type RunGraphContext = Pick<RuntimeInstanceContext, "runtimeDir">;
+export interface RunLifecycleFinalizationState {
+    interruptReason: null | string;
+    interrupted: boolean;
+}
+export interface RunLifecycle extends LocalServiceLifecycle {
+    commitFinalization(status?: string): RunLifecycleFinalizationState;
+    dispose(): void;
+    finalizeForControllerExit(reason?: unknown): boolean;
+    getInterruptReason(): null | string;
+    heartbeat(metadata?: unknown): void;
+    installSignalHandlers(): void;
+    isMaintenanceStopCoordinated(): boolean;
+    isStopRequested(): boolean;
+    manifestPath: string;
+    markFinished(status?: string): void;
+    markRunning(): void;
+    registerService(config: LifecycleServiceConfig, supervisor: SupervisedProcessHandle, ownership: SupervisedProcessReady, cwd: string): void;
+    removeManifest(): Promise<void>;
+    removeSignalHandlers(): void;
+    requestStop(reason?: unknown): void;
+    runId: string;
+    maintenanceStopSignal: AbortSignal;
+    signal: AbortSignal;
+    startHeartbeat(intervalMs?: unknown, metadataProvider?: null | (() => unknown)): () => void;
+    trackGraphContext(context: Readonly<RunGraphContext>): void;
+    unregisterService(supervisorPid: number): void;
+}
+interface RunLifecycleOwnership {
+    incarnationId: string;
+    pid: number;
+    processIdentity: null | string;
+    productDir: string;
+    published: boolean;
+    runId: string;
+}
+interface OwnedRunLifecycleState {
+    manifest: RunManifest | null;
+    ownership: RunLifecycleOwnership;
+    productDir: string;
+}
+export declare function createUnpublishedRunLifecycle(productDir: string, options?: Readonly<RunLifecycleOptions>): RunLifecycle;
+export declare function cleanupOwnedRunLifecycleWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>, lifecycle: Readonly<RunLifecycle>): boolean;
+export declare function readOwnedRunLifecycleWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>, lifecycle: Readonly<RunLifecycle>): OwnedRunLifecycleState;
+export declare function findPortOwner(productDir: string, { host, port }: Readonly<RunPortQuery>): RunPortOwner | null;
+export declare function isRunManifestActive(manifest: Readonly<RunManifest>): boolean;
+export declare function disposeFailedRunLifecycle(lifecycle: RunLifecycle): void;
+export {};

package/dist/environment/lifecycle-controller.js

@@ -0,0 +1 @@
+import x from"crypto";import{isTerminalRunStatus as U}from"../process/runs/schema.js";import{observeProcessCreationIdentity as M}from"../process/index.js";import{normalizeOperationReason as _}from"../domain/operation-reason.js";import{finalizeLiveRunArtifact as B}from"../evidence/index.js";import{captureProcessCreationIdentity as Y}from"../process/service-processes.js";import{requireProductLifecycleFenceProductDir as J,withProductLifecycleFence as K}from"../process/lifecycle-fence.js";import{createRunManifest as Q,listRunManifests as $,readRunMaintenanceStopRequest as X,removeRunManifestFile as G,requireSafeRunId as Z,RUN_MANIFEST_SCHEMA_VERSION as ee,runManifestPath as te,writeRunManifest as ne}from"../process/runs/manifest.js";const re=1e3,ie=String,T=new WeakMap;export function createUnpublishedRunLifecycle(n,r={}){const i=r.runId===void 0?le():Z(r.runId,"Testkit run id"),a=te(n,i),s=new AbortController,m=new AbortController,u=r.pid===void 0?process.pid:r.pid;if(!Number.isSafeInteger(u)||u<0)throw new Error("Testkit run pid must be a non-negative safe integer");const b=u>0?Y(u):null;if(u>0&&b===null)throw new Error(`Could not capture the Testkit run process identity for pid ${u.toString()}`);let f={incarnationId:x.randomUUID(),schemaVersion:ee,runId:i,pid:u,processIdentity:typeof b=="string"?b:null,controller:se(r.controller),status:"starting",startedAt:new Date().toISOString(),heartbeatAt:r.heartbeat===!1?null:new Date().toISOString(),interruptReason:null,services:[],runtimeDirs:[]};const O=[];let w,D=null;const y=new Set,S=new Set,P=r.keepAlive===!0?setInterval(()=>{},re):null;let R=null,g=null,v=null,q=!1;function j(e){const t=T.get(I);if(!t)throw new Error("Testkit run lifecycle ownership is unavailable");if(!t.published){Q(n,e),t.published=!0;return}ne(n,e)}function A(){const e=X(n,i);return e===null||e.targetIncarnationId!==f.incarnationId||e.targetPid!==u||e.targetProcessIdentity!==f.processIdentity||e.coordinatorPid===D?.coordinatorPid&&e.coordinatorProcessIdentity===D.coordinatorProcessIdentity?null:M(e.coordinatorPid,e.coordinatorProcessIdentity)==="different"?(D=e,null):e}function h(e){k("mutate run state");const t=oe(f);e(t),t.heartbeatAt!==null&&(t.heartbeatAt=new Date().toISOString()),j(t),f=t}function k(e){if(g!==null)throw new Error(`Cannot ${e} after Testkit run ${i} finalization is committed`)}function W(){R||(R=setInterval(()=>{},1e3))}function N(){R&&(clearInterval(R),R=null)}function z(){for(const e of S)clearInterval(e);S.clear()}function F(e="controller process exited before Testkit run finalized"){if(q||U(f.status))return!1;const t=_(e,"controller process exited before Testkit run finalized"),o=new Date,l=f.status==="interrupting"||s.signal.aborted?"interrupted":"failed",c=l==="interrupted"?f.interruptReason??v??t:t;return h(p=>{p.status=l,p.finishedAt=o.toISOString(),p.interruptReason=c,p.heartbeatAt!==null&&(p.heartbeatAt=o.toISOString())}),B(n,{runId:i,reason:c,status:l,finishedAt:o}),!0}const H=()=>{F()};process.on("exit",H);const I={runId:i,manifestPath:a,maintenanceStopSignal:m.signal,signal:s.signal,commitFinalization(e="finished"){if(g!==null)return g;const t=A(),o=s.signal.aborted||t!==null||f.status==="interrupting",l=o?f.interruptReason??v??t?.reason??"run interrupted":null,c=Object.freeze({interruptReason:l,interrupted:o});return h(p=>{p.status=o?"interrupted":e,p.finishedAt=new Date().toISOString(),p.interruptReason=l}),g=c,z(),c},getInterruptReason(){return f.interruptReason??v},isMaintenanceStopCoordinated(){return A()!==null},isStopRequested(){return s.signal.aborted||g?.interrupted===!0},markRunning(){h(e=>{e.status="running"})},markFinished(e="finished"){h(t=>{t.status=e,t.finishedAt=new Date().toISOString()})},heartbeat(e={}){h(t=>{t.heartbeatAt=new Date().toISOString(),e&&typeof e=="object"&&!Array.isArray(e)&&(t.session={...t.session||{},...e})})},startHeartbeat(e=5e3,t=null){k("start a run heartbeat");const o=Number.isFinite(Number(e))&&Number(e)>0?Math.floor(Number(e)):5e3,l=setInterval(()=>{let c;try{c=typeof t=="function"?t():{}}catch{c={}}I.heartbeat(c)},o);return l.unref(),S.add(l),()=>{clearInterval(l),S.delete(l)}},requestStop(e="interrupted"){if(g!==null||U(f.status))return;const t=A(),o=t?t.reason:_(e,"interrupted"),l=!s.signal.aborted;l&&(v=o),W();let c=null;if(l)try{h(d=>{d.status="interrupting",d.interruptReason=o})}catch(d){c=d instanceof Error?d:new Error("Failed to persist the Testkit stop request",{cause:d})}t!==null&&!m.signal.aborted&&m.abort(new Error(`Testkit run ${i} is being stopped by external maintenance`));const p=[...y].map(({supervisor:d})=>d.stop(t===null?void 0:Date.parse(t.requestedAt)+d.shutdownTimeoutMs));if(Promise.allSettled(p).then(N),s.signal.aborted||s.abort(new Error(`testkit run interrupted (${o})`)),!!l&&c!==null)throw c},trackGraphContext(e){h(t=>{ue(t.runtimeDirs,e.runtimeDir)})},registerService(e,t,o,l){if(k("register application service ownership"),o.pid!==t.pid||(process.platform==="win32"?o.recovery.processGroupId!==null:o.recovery.processGroupId!==o.pid))throw new Error("Application service supervisor returned an invalid ownership handoff");const c={supervisor:t,unsubscribe:()=>{}};y.add(c);const p=ae(e);h(d=>{d.services=d.services.filter(C=>C.pid!==o.pid),d.services.push({serviceName:e.name,runtimeLabel:e.runtimeLabel,command:e.testkit.local.start||null,cwd:l,pid:o.pid,processGroupId:o.recovery.processGroupId,processIdentity:o.recovery.creationIdentity,ports:p,startedAt:new Date().toISOString(),shutdownTimeoutMs:t.shutdownTimeoutMs,shutdownDeadlineAt:t.shutdownDeadlineAt})}),c.unsubscribe=t.onShutdownStarted(d=>{h(C=>{const E=C.services.find(V=>V.pid===o.pid);E&&(E.shutdownDeadlineAt=E.shutdownDeadlineAt==null?d:Math.min(E.shutdownDeadlineAt,d))})})},unregisterService(e){k("unregister application service ownership");for(const t of y)t.supervisor.pid===e&&(t.unsubscribe(),y.delete(t));h(t=>{t.services=t.services.filter(o=>o.pid!==e)})},installSignalHandlers(){if(!(O.length>0)&&!(u!==process.pid||M(u,f.processIdentity)!=="matches")){for(const e of["SIGINT","SIGTERM","SIGHUP"]){const t=I.requestStop.bind(I,e);process.on(e,t),O.push([e,t])}process.platform==="win32"&&(w=setInterval(()=>{const e=A();e!==null&&(clearInterval(w),I.requestStop(e.reason))},100),w.unref(),S.add(w))}},removeSignalHandlers(){w&&(clearInterval(w),S.delete(w),w=void 0);for(const[e,t]of O.splice(0))process.off(e,t)},async removeManifest(){await K(n,e=>cleanupOwnedRunLifecycleWithinLifecycleFence(e,I))},finalizeForControllerExit:F,dispose(){q=!0;for(const e of y)e.unsubscribe();process.off("exit",H),I.removeSignalHandlers(),P&&clearInterval(P),N(),z()}};return T.set(I,{incarnationId:f.incarnationId,pid:u,processIdentity:f.processIdentity,productDir:n,published:!1,runId:i}),I}function oe(n){const r={...n,controller:n.controller===null?null:{...n.controller},runtimeDirs:[...n.runtimeDirs],services:n.services.map(i=>({...i,ports:i.ports.map(a=>({...a}))}))};return n.session!==void 0&&(r.session=n.session===null?null:{...n.session}),r}function se(n){return!n||typeof n!="object"||Array.isArray(n)?null:Object.fromEntries(Object.entries(n).filter(([,r])=>r!==void 0).map(([r,i])=>[r,i===null?null:ie(i)]))}export function cleanupOwnedRunLifecycleWithinLifecycleFence(n,r){const{manifest:i,ownership:a,productDir:s}=readOwnedRunLifecycleWithinLifecycleFence(n,r);if(!i)return!1;if(i.services.length>0)throw new Error(`Cannot clean Testkit run ${r.runId} service ownership while holding the lifecycle fence`);return G(s,r.runId),a.published=!1,!0}export function readOwnedRunLifecycleWithinLifecycleFence(n,r){const i=J(n),a=T.get(r);if(!a||a.productDir!==i)throw new Error("Cannot clean a Testkit run without matching lifecycle ownership");if(a.runId!==r.runId)throw new Error("Testkit run lifecycle identity has been modified");const s=$(i).find(m=>m.runId===r.runId);if(s!==void 0&&(s.incarnationId!==a.incarnationId||s.pid!==a.pid||s.processIdentity!==a.processIdentity))throw new Error(`Testkit run ${r.runId} ownership no longer matches its manifest`);return{manifest:s??null,ownership:a,productDir:i}}export function findPortOwner(n,{host:r,port:i}){const a=$(n);for(const s of a)for(const m of s.services)for(const u of m.ports)if(L(u.host)===L(r)&&u.port===Number(i))return{manifest:s,service:m,active:isRunManifestActive(s)};return null}export function isRunManifestActive(n){return n.pid>0&&M(n.pid,n.processIdentity)!=="different"}function ae(n){const r=new Set,i=[];for(const a of[n.testkit.local.baseUrl,n.testkit.local.readyUrl])if(a)try{const s=new URL(a),m=L(s.hostname),u=Number(s.port||(s.protocol==="https:"?443:80)),b=`${m}:${u.toString()}`;if(r.has(b))continue;r.add(b),i.push({host:m,port:u})}catch{}return i}function ue(n,r){r&&(n.includes(r)||n.push(r))}function le(){return`${Date.now().toString()}-${process.pid.toString()}-${x.randomBytes(4).toString("hex")}`}function L(n){return n?n==="::1"?"127.0.0.1":n:"127.0.0.1"}export function disposeFailedRunLifecycle(n){const r=T.get(n);n.dispose(),n.removeSignalHandlers(),r?.published===!0&&G(r.productDir,n.runId)}

package/dist/environment/lifecycle.d.ts

@@ -0,0 +1,29 @@
+import type { LocalPostgresCleanupResult } from "../database/cleanup.js";
+import { type ProductLifecycleFence } from "../process/lifecycle-fence.js";
+import { type RunManifest } from "../process/runs/manifest.js";
+import { type RunLifecycle, type RunLifecycleOptions } from "./lifecycle-controller.js";
+export interface RunCleanupSummary {
+    cleaned: RunManifest[];
+    resourceCleanup: LocalPostgresCleanupResult;
+    skippedActive: RunManifest[];
+    stoppedActive: RunManifest[];
+}
+interface RunCleanupOptions {
+    includeActive?: boolean;
+}
+export interface RunCleanupWithinLifecycleFenceOptions {
+    protectedLiveRunIds?: ReadonlySet<string>;
+}
+export declare function startRunLifecycle(productDir: string, options?: Readonly<RunLifecycleOptions>): Promise<RunLifecycle>;
+export declare function startRunLifecycleWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>, options?: Readonly<RunLifecycleOptions>): Promise<RunLifecycle>;
+export declare function cleanupRuns(productDir: string, { includeActive }?: Readonly<RunCleanupOptions>): Promise<RunCleanupSummary>;
+export declare function cleanupRunsWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>, { protectedLiveRunIds }?: Readonly<RunCleanupWithinLifecycleFenceOptions>): Promise<RunCleanupSummary>;
+export declare function cleanupStaleRuns(productDir: string): Promise<RunManifest[]>;
+export declare function cleanupStaleRunsWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>): Promise<RunManifest[]>;
+export declare function cleanupOwnedRunLifecycleResourcesWithinLifecycleFence(fence: Readonly<ProductLifecycleFence>, lifecycle: Readonly<RunLifecycle>): Promise<boolean>;
+export { listRunManifests, RunManifestInventoryError, type RunManifest, type RunManifestController, type RunManifestPort, type RunManifestService, } from "../process/runs/manifest.js";
+export { stopRunById, stopRunManifest, type StoppedRun } from "./run-stopping.js";
+export { cleanupOwnedRunLifecycleWithinLifecycleFence, findPortOwner, isRunManifestActive, } from "./lifecycle-controller.js";
+export type { RunLifecycleOptions, RunPortQuery, RunPortOwner, RunLifecycleFinalizationState, RunLifecycle, } from "./lifecycle-controller.js";
+export { isPidRunning } from "../process/runs/stop.js";
+export { formatRunSummary } from "../process/runs/manifest.js";

package/dist/environment/lifecycle.js

@@ -0,0 +1 @@
+import{formatRunSummary as w}from"../process/runs/manifest.js";import{cleanupOrphanedLocalInfrastructure as R,cleanupTerminalRunLocalInfrastructure as m}from"../database/index.js";import{resetResultArtifacts as v}from"../evidence/index.js";import{requireProductLifecycleFenceProductDir as d,withProductLifecycleFence as l}from"../process/lifecycle-fence.js";import{listRunManifests as u,removeRunManifestFile as y,requireSafeRunId as I}from"../process/runs/manifest.js";import{stopRunManifest as A}from"./run-stopping.js";import{createUnpublishedRunLifecycle as L,disposeFailedRunLifecycle as k,isRunManifestActive as a,cleanupOwnedRunLifecycleWithinLifecycleFence as S,readOwnedRunLifecycleWithinLifecycleFence as p}from"./lifecycle-controller.js";import{reconcileInactiveRunArtifact as g,reconcileOrphanedLiveRunArtifact as x}from"./lifecycle-artifacts.js";class f extends Error{constructor(n){super(`Stale Testkit run ${n} still owns application services and requires phased cleanup`),this.name="StaleRunServiceCleanupRequiredError"}}export async function startRunLifecycle(e,n={}){for(;;){await cleanupStaleRuns(e);try{return await l(e,t=>startRunLifecycleWithinLifecycleFence(t,n))}catch(t){if(!(t instanceof f))throw t}}}export async function startRunLifecycleWithinLifecycleFence(e,n={}){const t=d(e);h(t),await cleanupStaleRunsWithinLifecycleFence(e);const c=u(t).find(i=>!a(i)&&i.services.length>0);if(c!==void 0)throw new f(c.runId);h(t);const r=L(t,n);try{return r.installSignalHandlers(),n.resetResultsBeforePublish===!0&&v(t),r.markRunning(),r}catch(i){throw k(r),i}}function h(e){const n=u(e).find(a);if(n)throw new Error(`Active Testkit run ${w(n)} already owns this product`)}export async function cleanupRuns(e,{includeActive:n=!1}={}){const t=[],c=[];for(;;){const i=await l(e,()=>u(e).flatMap(s=>{const o=a(s);return n&&o||!o&&s.services.length>0?[{active:o,manifest:s}]:[]}));if(i.length===0)break;for(const s of i)await A(e,s.manifest,{reason:s.active?"cleanup":"stale run process not active"}),s.active?t.push(s.manifest):c.push(s.manifest)}const r=await l(e,i=>cleanupRunsWithinLifecycleFence(i));return{...r,cleaned:[...t,...c,...r.cleaned],stoppedActive:t}}export async function cleanupRunsWithinLifecycleFence(e,{protectedLiveRunIds:n=new Set}={}){const t=d(e),c=u(t),r={cleaned:[],skippedActive:[],stoppedActive:[]};for(const i of c){if(a(i)||i.services.length>0){r.skippedActive.push(i);continue}g(t,i),y(t,O(i)),r.cleaned.push(i)}return x(t,{activeRunIds:new Set([...r.skippedActive.map(i=>i.runId).filter(i=>typeof i=="string"),...n])}),r.resourceCleanup=await R(t),{cleaned:r.cleaned,resourceCleanup:r.resourceCleanup,skippedActive:r.skippedActive,stoppedActive:r.stoppedActive}}export async function cleanupStaleRuns(e){const n=[];for(;;){const t=await cleanupRuns(e);if(n.push(...t.cleaned),!t.skippedActive.some(r=>!a(r)&&r.services.length>0))return n}}export async function cleanupStaleRunsWithinLifecycleFence(e){return(await cleanupRunsWithinLifecycleFence(e)).cleaned}export async function cleanupOwnedRunLifecycleResourcesWithinLifecycleFence(e,n){const t=p(e,n);if(t.manifest===null)throw new Error(`Cannot clean terminal Testkit run ${n.runId} resources without its owned manifest`);if(t.manifest.services.length>0)throw new Error(`Cannot clean terminal Testkit run ${n.runId} resources while service ownership remains published`);const c=C(t.manifest);await m(e,c);const r=p(e,n);if(r.manifest===null||!F(r.manifest,c))throw new Error(`Cannot remove terminal Testkit run ${n.runId} because its manifest changed during resource cleanup`);return S(e,n)}function C(e){if(e.status!=="failed"&&e.status!=="finished"&&e.status!=="interrupted")throw new Error(`Cannot clean Testkit run ${e.runId} database resources before terminal finalization`);if(typeof e.finishedAt!="string"||e.finishedAt.length===0)throw new Error(`Cannot clean terminal Testkit run ${e.runId} database resources without a completion time`);return{finishedAt:e.finishedAt,incarnationId:e.incarnationId,pid:e.pid,processIdentity:e.processIdentity,runId:e.runId,status:e.status}}function F(e,n){return e.runId===n.runId&&e.incarnationId===n.incarnationId&&e.pid===n.pid&&e.processIdentity===n.processIdentity&&e.finishedAt===n.finishedAt&&e.status===n.status&&e.services.length===0}function O(e){return I(e.runId,"Testkit run manifest runId")}export{listRunManifests,RunManifestInventoryError}from"../process/runs/manifest.js";export{stopRunById,stopRunManifest}from"./run-stopping.js";export{cleanupOwnedRunLifecycleWithinLifecycleFence,findPortOwner,isRunManifestActive}from"./lifecycle-controller.js";export{isPidRunning}from"../process/runs/stop.js";export{formatRunSummary}from"../process/runs/manifest.js";

package/dist/environment/maintenance.d.ts

@@ -0,0 +1,68 @@
+import type { NormalizedServiceConfig } from "../config/loader/index.js";
+import type { DatabaseResourceCleanupEntry, LocalPostgresCleanupResult } from "../database/cleanup.js";
+import { type RunManifest, type StoppedRun } from "./lifecycle.js";
+import { type RuntimeCleanupTarget, type RuntimeGraphStatus, type RunStatus } from "./status-runtime.js";
+import type { DesiredRuntimeGraph } from "./planning-types.js";
+export type { RuntimeCleanupTarget, RuntimeGraphStatus, RunStatus } from "./status-runtime.js";
+export type { RunManifest } from "../process/runs/manifest.js";
+export type { StoppedRun } from "./run-stopping.js";
+export interface ResourceCleanupSummary {
+    kept: DatabaseResourceCleanupEntry[];
+    removed: DatabaseResourceCleanupEntry[];
+    skipped?: LocalPostgresCleanupResult["skipped"];
+    stopped?: LocalPostgresCleanupResult["stopped"];
+    targets: DatabaseResourceCleanupEntry[];
+}
+interface RunCleanupPreview {
+    cleaned: RunManifest[];
+    skippedActive: RunManifest[];
+    stoppedActive: RunManifest[];
+}
+export interface EnvironmentInventory {
+    runtimeGraphs: RuntimeGraphStatus[];
+    runs: RunStatus;
+}
+export type RunSelection = {
+    kind: "latest-active";
+} | {
+    kind: "all";
+} | {
+    kind: "run";
+    runId: string;
+};
+export interface EnvironmentCleanupRequest {
+    kind: "cleanup";
+    desiredGraphs: readonly DesiredRuntimeGraph[];
+    serviceName: string | null;
+    dryRun: boolean;
+    resources: boolean;
+}
+export interface EnvironmentDestroyRequest {
+    kind: "destroy";
+    configs: readonly Readonly<NormalizedServiceConfig>[];
+    destroyOwnedResources?: boolean;
+}
+export interface EnvironmentCleanupResult extends RunCleanupPreview {
+    dryRun: boolean;
+    targets: RuntimeCleanupTarget[];
+    runtimeCleaned: RuntimeCleanupTarget[];
+    resourceCleanup: ResourceCleanupSummary;
+    automaticResourceCleanup: ResourceCleanupSummary[];
+}
+export interface CacheMaintenance<Result> {
+    result: Result;
+    prune(): void | Promise<void>;
+}
+export interface EnvironmentMaintenance {
+    inspect(desiredGraphs: readonly DesiredRuntimeGraph[], serviceName?: string | null): EnvironmentInventory;
+    inspectRuns(): Array<RunManifest & {
+        active: boolean;
+    }>;
+    stop(selection: RunSelection, reason: string): Promise<StoppedRun[]>;
+    maintain(request: EnvironmentDestroyRequest): Promise<void>;
+    maintain<Result>(request: EnvironmentCleanupRequest, planOtherCaches: () => CacheMaintenance<Result>): Promise<{
+        environment: EnvironmentCleanupResult;
+        otherCaches: Result;
+    }>;
+}
+export declare function createEnvironmentMaintenance(productDir: string): EnvironmentMaintenance;

package/dist/environment/maintenance.js

@@ -0,0 +1 @@
+import o from"fs";import p from"path";import{cleanupOwnedLocalDatabaseResources as G,cleanupOrphanedLocalInfrastructure as L,destroyOwnedLocalDatabaseResources as x,destroyRuntimeDatabase as C,destroyServiceDatabaseCache as I,isDatabaseStateDir as k}from"../database/index.js";import{cleanupRuns as A,cleanupRunsWithinLifecycleFence as g,isRunManifestActive as m,listRunManifests as d,stopRunManifest as F}from"./lifecycle.js";import{findGraphDirsForService as N,findRuntimeStateDirs as E}from"./state.js";import{collectRuntimeGraphStatus as M,collectRunStatus as T}from"./status-runtime.js";import{withProductLifecycleFence as w}from"../process/lifecycle-fence.js";import{pruneEmptyDir as O}from"../process/files/directory-status.js";export function createEnvironmentMaintenance(e){async function n(t,a){if(t.kind==="destroy")return $(e,t.configs,t);if(a===void 0)throw new Error("Cleanup requires a cache maintenance plan");if(t.dryRun)return P(e,t,a);const s=await A(e,{includeActive:!0});return w(e,i=>P(e,t,a,i,s))}return{inspect(t,a=null){return{runtimeGraphs:M(e,{desiredGraphs:t,serviceName:a}),runs:T(e)}},inspectRuns:()=>d(e).map(t=>({...t,active:m(t)})),async stop(t,a){const s=await w(e,()=>{const r=d(e);return t.kind==="run"?r.filter(u=>u.runId===t.runId):t.kind==="all"?r:r.filter(m).slice(-1)}),i=[];for(const r of s)i.push(await F(e,r,{reason:a}));return i},maintain:n}}async function $(e,n,t={}){j(e,n),await A(e,{includeActive:!0}),await w(e,async a=>{const s=await g(a);b(s,"destroy");const i=new Set(n.flatMap(r=>[r.stateDir,...N(e,r.name)]));for(const r of i){if(!o.existsSync(r))continue;const u=E(r,k);for(const l of u)await C({productDir:e,stateDir:l});o.rmSync(r,{recursive:!0,force:!0})}for(const r of n)await I(e,r.name);t.destroyOwnedResources&&await x(a),await L(e)})}async function P(e,n,t,a=null,s=null){const{dryRun:i}=n,r=n.serviceName||null,u=n.resources;let l,h=[];if(i)l=U(e);else{if(a===null)throw new Error("Destructive cleanup requires the product lifecycle fence");const c=await g(a);b(c,"cleanup"),l={...c,cleaned:[...s?.cleaned??[],...c.cleaned],stoppedActive:[...s?.stoppedActive??[]]},h=[...s===null?[]:[s.resourceCleanup],c.resourceCleanup]}const y=M(e,{desiredGraphs:n.desiredGraphs,serviceName:r}).flatMap(c=>c.staleRuntimeDirs.filter(f=>!f.active).map(f=>({graph:c.name,runtimeId:f.id,path:f.path}))),v=t(),R=[];let S={targets:[],removed:[],kept:[],skipped:[],stopped:[]};if(!i){for(const c of y)await B(e,c.path),R.push(c);await v.prune(),O(p.join(e,".testkit","_graphs"))}return u&&(S=await G(e,{dryRun:i})),{environment:{...l,dryRun:i,targets:y,runtimeCleaned:R,resourceCleanup:S,automaticResourceCleanup:h},otherCaches:v.result}}function b(e,n){if(e.skippedActive.length!==0)throw new Error(`A Testkit run started while ${n} was acquiring exclusive product ownership; retry after the run finishes`)}function j(e,n){const t=o.realpathSync.native(p.resolve(e));for(const a of n)if(o.realpathSync.native(p.resolve(a.productDir))!==t)throw new Error(`Cannot destroy service ${a.name} from a different Testkit product`)}async function B(e,n){if(!n||!o.existsSync(n))return;const t=E(n,k);for(const a of t)await C({productDir:e,stateDir:a});o.rmSync(n,{recursive:!0,force:!0})}function U(e){const n={cleaned:[],skippedActive:[],stoppedActive:[]};for(const t of d(e))m(t)?n.skippedActive.push(t):n.cleaned.push(t);return n}

package/dist/environment/planning-types.d.ts

@@ -0,0 +1,35 @@
+import type { RuntimeDependencyConfig } from "../config/loader/dependencies.js";
+import type { DatabaseReservationService, RuntimeDatabaseReservation } from "../database/runtime-reservations.js";
+export interface RuntimeServiceSpec extends RuntimeDependencyConfig {
+    testkit: RuntimeDependencyConfig["testkit"] & DatabaseReservationService["testkit"] & {
+        runtime: {
+            instances: number;
+            maxConcurrentTasks: number;
+        };
+    };
+}
+export interface RuntimeSelection<Config extends RuntimeServiceSpec = RuntimeServiceSpec> {
+    config: Config;
+    runtimeConfigs: readonly Config[];
+    runtimeKey: string;
+    runtimeNames: readonly string[];
+}
+export interface RuntimeGraph<Config extends RuntimeServiceSpec = RuntimeServiceSpec> {
+    dirName: string;
+    instanceCount: number;
+    key: string;
+    maxConcurrentTasks: number;
+    portNamespaceIndex: number;
+    portNamespaceStride: number;
+    resourceReservations: RuntimeDatabaseReservation[];
+    runtimeConfigs: readonly Config[];
+    runtimeNames: readonly string[];
+    targetNames: string[];
+}
+export interface DesiredRuntimeGraph {
+    dirName: string;
+    instanceCount: number;
+    key: string;
+    runtimeNames: string[];
+    targetNames: string[];
+}

package/dist/environment/planning-types.js

@@ -0,0 +1 @@
+export{};

package/dist/environment/readiness.d.ts

@@ -0,0 +1,12 @@
+export interface LocalReadinessConfig {
+    name: string;
+    productDir: string;
+    runtimeLabel: string;
+    testkit: {
+        local: {
+            baseUrl: string;
+            readyUrl?: false | null | string;
+        };
+    };
+}
+export declare function assertLocalServicePortsAvailable(config: Readonly<LocalReadinessConfig>): Promise<void>;

package/dist/environment/readiness.js

@@ -0,0 +1 @@
+import{cleanupStaleRuns as m,findPortOwner as p,formatRunSummary as a}from"./lifecycle.js";import{socketFromUrl as w}from"./template.js";import{isPortInUse as c}from"../process/readiness.js";const s=String;export async function assertLocalServicePortsAvailable(t){const l=[t.testkit.local.baseUrl,t.testkit.local.readyUrl],o=new Set;for(const i of l){const e=typeof i=="string"?w(i):null;if(!e)continue;const r=`${e.host}:${s(e.port)}`;if(!o.has(r)&&(o.add(r),await c(e)&&await m(t.productDir),await c(e))){const n=p(t.productDir,e),u=n?n.active?` Active testkit run ${s(a(n.manifest))} owns ${r} via ${s(n.service.runtimeLabel)}:${s(n.service.serviceName)}.`:` Stale testkit run ${s(a(n.manifest))} owns ${r}.`:"";throw new Error(`Cannot start "${t.runtimeLabel}:${t.name}" because ${r} is already in use. Stop the existing process and rerun testkit.${u}`)}}}

package/dist/environment/ready-environment.d.ts

@@ -0,0 +1,17 @@
+import { type DatabaseInfo } from "../database/index.js";
+import type { RuntimeInstanceContext } from "./runtime-contexts.js";
+import type { ReadyServiceConfig } from "./runtime-service.js";
+export interface ReadyService {
+    readonly baseUrl: string | null;
+    readonly config: ReadyServiceConfig;
+    readonly database: Readonly<DatabaseInfo> | null;
+}
+export interface ReadyEnvironment {
+    readonly graphKey: string;
+    readonly leaseDir: string;
+    readonly leaseId: string;
+    readonly runtimeId: string;
+    readonly services: ReadonlyMap<string, ReadyService>;
+    readonly targetNames: readonly string[];
+}
+export declare function createReadyEnvironment(context: RuntimeInstanceContext, lease: Pick<ReadyEnvironment, "leaseDir" | "leaseId">): ReadyEnvironment;

package/dist/environment/ready-environment.js

@@ -0,0 +1 @@
+import{readDatabaseInfo as s}from"../database/index.js";export function createReadyEnvironment(t,n){const a=new Map(t.runtimeConfigs.map(e=>[e.name,s(e.stateDir)]));return{...n,graphKey:t.graphKey,runtimeId:t.runtimeId,targetNames:[...t.targetNames],services:new Map(t.runtimeConfigs.map(e=>{const r={...e.testkit.templateContext};return delete r.databaseBindingsReader,[e.name,{baseUrl:e.testkit.local?.baseUrl||null,database:a.get(e.name)??null,config:{...e,testkit:{...e.testkit,templateContext:{...r,databaseBindingsByService:a}}}}]}))}}

package/dist/environment/run-environment.d.ts

@@ -0,0 +1,38 @@
+import { type RuntimeManagerGraph, type RuntimeManagerRuntimeOptions, type RuntimeRequirement, type RuntimeCapacityRequirement, type RuntimeManagerAcquireOptions, type RuntimeManagerReleaseOptions, type RuntimeManagerGraphStats } from "./runtime-manager.js";
+import type { ReadyEnvironment } from "./ready-environment.js";
+import { type CommittedRunFinalization } from "../evidence/finalization.js";
+export type { RuntimeManagerGraphStats, RuntimeManagerRuntimeOptions, RuntimeManagerGraph } from "./runtime-manager.js";
+export interface RuntimeGraphIdentity {
+    readonly key: string;
+    readonly targetNames: readonly string[];
+}
+export interface RunProvisioningOptions {
+    heartbeat?: boolean;
+    keepAlive?: boolean;
+    resetResultsBeforePublish?: boolean;
+    runId?: string;
+}
+export interface RunProvisioning {
+    start(options: Readonly<RunProvisioningOptions>): Promise<ProvisionedRun>;
+}
+export interface ProvisionedRun {
+    readonly runId: string;
+    readonly signal: AbortSignal;
+    readonly committedFinalization: CommittedRunFinalization | null;
+    isStopRequested(): boolean;
+    getInterruptReason(): string | null;
+    requestStop(reason?: unknown): void;
+    beginFinalization(): void;
+    dispose(): void;
+    provision(graphs: readonly RuntimeManagerGraph[], options: Readonly<RuntimeManagerRuntimeOptions>): void;
+    acquire(requirement: Readonly<RuntimeRequirement>, options?: Readonly<RuntimeManagerAcquireOptions>): Promise<ReadyEnvironment>;
+    canAcquire(requirement: Readonly<RuntimeCapacityRequirement>): boolean;
+    release(leaseId: string, options?: Readonly<RuntimeManagerReleaseOptions>): Promise<void>;
+    cleanupAll(): Promise<void>;
+    getStats(): RuntimeManagerGraphStats[];
+    getGraph(graphKey: string): RuntimeGraphIdentity | null;
+    getGraphFailure(graphKey: string): string | null;
+    markGraphFailed(graphKey: string, message: string): void;
+    finish<Result>(status: "failed" | "passed", seal: (state: Readonly<CommittedRunFinalization>) => Result, mode: "normal" | "recovery"): Promise<Result>;
+}
+export declare function createLocalRunEnvironment(productDir: string): RunProvisioning;

package/dist/environment/run-environment.js

@@ -0,0 +1 @@
+import{cleanupOwnedRunLifecycleResourcesWithinLifecycleFence as w,cleanupRunsWithinLifecycleFence as y,listRunManifests as R,startRunLifecycle as v}from"./lifecycle.js";import{createRuntimeManager as F}from"./runtime-manager.js";import{resolveCommittedRunFinalization as q}from"../evidence/finalization.js";import{withProductLifecycleFence as I}from"../process/lifecycle-fence.js";export function createLocalRunEnvironment(s){return{async start(d){const n=await v(s,d),c=n.startHeartbeat(2e3,()=>({kind:"controller",status:n.isStopRequested()?"interrupting":"running"}));let i=null;const p=new Map,l=()=>{if(i===null)throw new Error("Run runtimes have not been provisioned");return i};let m=null;return{runId:n.runId,signal:n.signal,isStopRequested:()=>n.isStopRequested(),getInterruptReason:()=>n.getInterruptReason(),requestStop:e=>{n.requestStop(e)},beginFinalization:c,dispose(){c(),n.removeSignalHandlers(),n.dispose()},get committedFinalization(){return m},provision(e,t){if(i!==null)throw new Error("Run runtimes are already provisioned");i=F({productDir:s,graphs:e,lifecycle:n,runtimeOptions:t})},async acquire(e,t){const r=await l().acquire(e,t);p.set(r.leaseId,r);const{leaseId:o,leaseDir:u,runtimeId:a,graphKey:h,targetNames:f,services:g}=r;return{leaseId:o,leaseDir:u,runtimeId:a,graphKey:h,targetNames:f,services:g}},canAcquire:e=>l().canAcquire(e),async release(e,t){const r=p.get(e);r!==void 0&&(await l().release(r,t),p.delete(e))},async cleanupAll(){await i?.cleanupAll()},getStats:()=>i?.getStats()??[],getGraph(e){const t=i?.getGraph(e);return t?{key:t.key,targetNames:[...t.targetNames]}:null},getGraphFailure:e=>i?.getGraphFailure(e)??null,markGraphFailed:(e,t)=>{l().markGraphFailed(e,t)},async finish(e,t,r){return c(),I(s,async o=>{const u=R(s).find(a=>a.runId===n.runId);if(u!==void 0&&u.services.length>0)throw new Error(r==="normal"?"Cannot commit a run while application service ownership remains published":"Cannot publish terminal failure while application service ownership remains published");m??=q(e,n.commitFinalization(e==="failed"?"failed":"finished"));try{await y(o,{protectedLiveRunIds:new Set([n.runId])}),await w(o,n)}catch(a){if(r==="normal")throw a}return t(m)})}}}}}

package/dist/environment/run-stopping.d.ts

@@ -0,0 +1,13 @@
+import { type RunManifest } from "../process/runs/manifest.js";
+export interface StoppedRun {
+    pid: number;
+    reason: string;
+    runId: string;
+    stopped: true;
+}
+export interface StopRunOptions {
+    graceMs?: number;
+    reason?: unknown;
+}
+export declare function stopRunById(productDir: string, runId: string, options?: Readonly<StopRunOptions>): Promise<boolean>;
+export declare function stopRunManifest(productDir: string, manifest: Readonly<RunManifest>, options?: Readonly<StopRunOptions>): Promise<StoppedRun>;

package/dist/environment/run-stopping.js

@@ -0,0 +1 @@
+import{waitForPreparedRunStop as g,drainRunServices as M,requestProcessStop as _,runManifestServiceKey as F,sameRunManifestIncarnation as P}from"../process/runs/stop.js";import{observeProcessCreationIdentity as h,captureProcessCreationIdentity as N}from"../process/index.js";import{normalizeOperationReason as S}from"../domain/operation-reason.js";import{RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION as L}from"../process/runs/schema.js";import{finalizeLiveRunArtifact as v}from"../evidence/index.js";import{requireProductLifecycleFenceProductDir as q,withProductLifecycleFence as m}from"../process/lifecycle-fence.js";import{listRunManifests as E,readRunMaintenanceStopRequest as T,removeRunMaintenanceStopRequest as y,removeRunManifestFile as O,requireSafeRunId as k,writeRunMaintenanceStopRequest as $,prepareRunShutdownDeadlines as D,persistRunShutdownDeadlines as z}from"../process/runs/manifest.js";export async function stopRunById(r,t,i={}){const n=k(t,"Testkit run id"),e=await m(r,o=>A(o,n,i));if(e===null)return!1;const s=await g(e);return await C(r,e,s),!0}export async function stopRunManifest(r,t,i={}){const n=W(t),e=await m(r,o=>A(o,n,i,t));if(e===null)return{runId:n,pid:t.pid,reason:S(i.reason,"stopped"),stopped:!0};const s=await g(e);return C(r,e,s)}function A(r,t,i={},n=null){const e=q(r);let s=S(i.reason,"stopped");const o=E(e).find(a=>a.runId===t);if(o===void 0){if(n!==null&&n.pid>0&&n.processIdentity===null&&h(n.pid,n.processIdentity)==="unknown")throw new Error(`Cannot establish the creation identity of Testkit run process ${n.pid.toString()}; refusing unsafe stop`);return n!==null&&n.pid===0&&(v(e,{runId:t,reason:s,status:"interrupted"}),y(e,t)),null}if(n!==null&&!P(o,n))throw new Error(`Testkit run ${t} ownership changed before the stop request could be published`);const u=o.pid,f=u>0?h(u,o.processIdentity):"different";if(u===process.pid&&f==="matches")throw new Error(`Cannot stop active Testkit run ${t} from inside its own controller process`);if(f==="unknown")throw new Error(`Cannot establish the creation identity of Testkit run process ${u.toString()}; refusing unsafe stop`);let d=null,p=new Date().toISOString(),l=null;const I=T(e,t),c=I!==null&&I.targetIncarnationId===o.incarnationId&&I.targetPid===u&&I.targetProcessIdentity===o.processIdentity?I:null;c!==null&&(s=c.reason,p=c.requestedAt);let R=null;const w=()=>{if(R!==null)return R;const a=D(o,p);return f==="different"&&z(e,a),R=a,a};if(f==="matches"){if(l=o.processIdentity,l===null)throw new Error(`Testkit run process ${u.toString()} has no creation identity; refusing unsafe stop`);if(c!==null&&h(c.coordinatorPid,c.coordinatorProcessIdentity)!=="different")return d=c.coordinatorProcessIdentity,{controllerActive:!0,coordinatorProcessIdentity:d,graceMs:i.graceMs||2e3,manifest:w(),requestedAt:p,pid:u,productDir:e,reason:s,runId:t,targetProcessIdentity:l};if(d=N(process.pid),d===null)throw new Error("Could not capture the maintenance coordinator process identity");$(e,{coordinatorPid:process.pid,coordinatorProcessIdentity:d,reason:s,requestedAt:p,runId:t,schemaVersion:L,targetIncarnationId:o.incarnationId,targetPid:u,targetProcessIdentity:l}),w();try{process.platform!=="win32"&&_(u,l,"SIGINT")}catch(a){throw y(e,t),a}}return{controllerActive:f==="matches",coordinatorProcessIdentity:d,graceMs:i.graceMs||2e3,manifest:w(),requestedAt:p,pid:u,productDir:e,reason:s,runId:t,targetProcessIdentity:l}}async function C(r,t,i){for(;;){const n=await m(r,e=>U(e,t,i));if(n.result!==null)return n.result;await M(n.services,i)}}function U(r,t,i){const n=q(r),e=E(n).find(o=>o.runId===t.runId);if(e===void 0||!P(e,t.manifest))return V(n,t),{result:b(t),services:null};const s=e.services.filter(o=>!i.has(F(o)));return s.length>0?{result:null,services:s}:(v(n,{runId:t.runId,reason:t.reason,status:"interrupted"}),O(n,t.runId),{result:b(t),services:null})}function b(r){return{runId:r.runId,pid:r.pid,stopped:!0,reason:r.reason}}function V(r,t){const i=T(r,t.runId);i===null||i.coordinatorPid!==process.pid||i.coordinatorProcessIdentity!==t.coordinatorProcessIdentity||i.targetIncarnationId!==t.manifest.incarnationId||i.targetPid!==t.pid||i.targetProcessIdentity!==t.targetProcessIdentity||y(r,t.runId)}function W(r){return k(r.runId,"Testkit run manifest runId")}

package/dist/environment/runtime-contexts.d.ts

@@ -0,0 +1,32 @@
+import { type ProvisionDatabaseOptions } from "../database/index.js";
+import type { RuntimeServiceSpec, RuntimeGraph } from "./planning-types.js";
+import { type RuntimePreparationConfig, type RuntimePreparationOptions } from "./runtime-preparation.js";
+import { type LocalServiceLifecycle, type StartedLocalService, type StartLocalServicesOptions } from "./services.js";
+import { type RuntimeServiceConfig } from "./template.js";
+import type { ConfiguredStepServiceConfig } from "../steps/index.js";
+import type { ReadyServiceConfig } from "./runtime-service.js";
+export type RuntimeContextSourceConfig = RuntimeServiceSpec & RuntimeServiceConfig & ReadyServiceConfig & ConfiguredStepServiceConfig & {
+    stateDir: string;
+    testkit: RuntimeServiceSpec["testkit"] & RuntimeServiceConfig["testkit"] & ConfiguredStepServiceConfig["testkit"] & {
+        envFiles?: readonly string[];
+    };
+};
+export type RuntimeContextOptions = RuntimePreparationOptions & StartLocalServicesOptions & Pick<ProvisionDatabaseOptions, "skipSchemaSourceVerify">;
+export type RuntimeInstanceConfig = RuntimePreparationConfig & ReadyServiceConfig;
+export interface RuntimeInstanceContext {
+    graphDir: string;
+    graphKey: string;
+    preparationPromise: Promise<void> | null;
+    prepared: boolean;
+    runtimeConfigs: RuntimeInstanceConfig[];
+    runtimeDir: string;
+    runtimeId: string;
+    started: boolean;
+    startedServices: StartedLocalService[];
+    startupPromise: Promise<void> | null;
+    targetNames: string[];
+}
+export declare function createRuntimeInstanceContext(runtimeId: string, graph: RuntimeGraph<RuntimeContextSourceConfig>, productDir: string): RuntimeInstanceContext;
+export declare function ensureRuntimeInstanceReady(context: RuntimeInstanceContext, startApplicationServices: boolean, lifecycle: LocalServiceLifecycle, options?: Readonly<RuntimeContextOptions>): Promise<RuntimeInstanceContext>;
+export declare function cleanupRuntimeInstanceContext(context: RuntimeInstanceContext | null | undefined, lifecycle: LocalServiceLifecycle): Promise<void>;
+export declare function prepareDatabases(runtimeConfigs: readonly RuntimePreparationConfig[], options?: Readonly<RuntimeContextOptions>): Promise<void>;

package/dist/environment/runtime-contexts.js

@@ -0,0 +1 @@
+import p from"fs";import t from"path";import{provisionDatabase as m}from"../database/index.js";import{prepareRuntimeServices as o}from"./runtime-preparation.js";import{writeGraphMetadata as u}from"./state.js";import{startLocalServices as f,stopLocalServices as l}from"./services.js";import{resolveRuntimeInstanceConfigs as d}from"./template.js";export function createRuntimeInstanceContext(r,e,a){const i=t.join(a,".testkit","_graphs",e.dirName),s=t.join(i,"runtimes",r);p.mkdirSync(s,{recursive:!0}),u(i,e);const n=d(e.runtimeConfigs,r,s,{graphDirName:e.dirName,portNamespaceIndex:e.portNamespaceIndex,portNamespaceStride:e.portNamespaceStride});return{graphKey:e.key,targetNames:[...e.targetNames],graphDir:i,runtimeDir:s,runtimeId:r,runtimeConfigs:n,prepared:!1,preparationPromise:null,started:!1,startupPromise:null,startedServices:[]}}export async function ensureRuntimeInstanceReady(r,e,a,i={}){return r.prepared||(r.preparationPromise||(r.preparationPromise=(async()=>{await prepareDatabases(r.runtimeConfigs,{...i,signal:a.signal}),await o(r.runtimeConfigs,{...i,signal:a.signal}),r.prepared=!0})().finally(()=>{r.preparationPromise=null})),await r.preparationPromise),e&&!r.started&&(r.startupPromise||(r.startupPromise=(async()=>{r.startedServices=await f(r.runtimeConfigs,a,i),r.started=!0})().finally(()=>{r.startupPromise=null})),await r.startupPromise),r}async function c(r,e){r?.started&&(await l(r.startedServices,e),r.started=!1,r.startedServices=[])}export async function cleanupRuntimeInstanceContext(r,e){r&&await c(r,e)}export async function prepareDatabases(r,e={}){for(const a of r)await m(a,{progress:{reporter:e.reporter,setupRegistry:e.setupRegistry},signal:e.signal,skipSchemaSourceVerify:e.skipSchemaSourceVerify})}

package/dist/environment/runtime-manager.d.ts

@@ -0,0 +1,95 @@
+import { type RuntimeContextOptions, type RuntimeContextSourceConfig, type RuntimeInstanceContext } from "./runtime-contexts.js";
+import { type OperationTimingRegistry } from "../evidence/operation-timings.js";
+import type { RunLifecycle } from "./lifecycle.js";
+import type { RuntimeGraph } from "./planning-types.js";
+import { type ReadyEnvironment } from "./ready-environment.js";
+export type RuntimeManagerGraph = RuntimeGraph<RuntimeContextSourceConfig>;
+export interface RuntimeCapacityRequirement {
+    graphKey: string;
+    locks?: readonly string[];
+    resourceCost?: number;
+}
+export interface RuntimeRequirement extends RuntimeCapacityRequirement {
+    id: number;
+    startApplicationServices: boolean;
+    serviceName?: string;
+    targetName?: string;
+}
+export type RuntimeManagerRuntimeOptions = RuntimeContextOptions & {
+    operationTimingRegistry?: null | OperationTimingRegistry;
+};
+export interface CreateRuntimeManagerOptions {
+    graphs: readonly RuntimeManagerGraph[];
+    lifecycle: RunLifecycle;
+    productDir: string;
+    runtimeOptions?: Readonly<RuntimeManagerRuntimeOptions>;
+}
+export interface RuntimeManagerAcquireOptions {
+    operationTimingParentId?: null | string;
+}
+export interface RuntimeManagerReleaseOptions {
+    invalidate?: boolean;
+}
+interface RuntimeLeaseReleaseState {
+    leaseDir: boolean;
+    locks: boolean;
+    runtimeSlot: boolean;
+}
+interface RuntimeSlotResourceReservation {
+    key: string;
+    services: readonly string[];
+    units: number;
+}
+export interface RuntimeSlot {
+    activeLeaseCount: number;
+    activeResourceUnits: number;
+    context: null | RuntimeInstanceContext;
+    draining: boolean;
+    graph: RuntimeManagerGraph;
+    peakLeaseCount: number;
+    peakResourceUnits: number;
+    resourceReservations: RuntimeSlotResourceReservation[];
+    runtimeId: string;
+}
+export interface RuntimeLease extends ReadyEnvironment {
+    context: RuntimeInstanceContext;
+    lockNames: readonly string[];
+    released?: boolean;
+    releaseState?: RuntimeLeaseReleaseState;
+    resourceCost: number;
+    slot: RuntimeSlot;
+}
+export interface RuntimeManagerRuntimeStats {
+    peakLeaseCount: number;
+    peakResourceUnits: number;
+    resourceReservations: RuntimeSlotResourceReservation[];
+    runtimeId: string;
+}
+export interface RuntimeManagerResourceBudgetStats {
+    active: number;
+    available: number;
+    capacity: number;
+    key: string;
+    peakActive: number;
+    reserved: number;
+}
+export interface RuntimeManagerGraphStats {
+    graphKey: null | string;
+    maxConcurrentTasks: null | number;
+    resourceBudgets: RuntimeManagerResourceBudgetStats[];
+    runtimeCount: number;
+    runtimes: RuntimeManagerRuntimeStats[];
+    targetNames: string[];
+}
+export interface RuntimeManager {
+    acquire<Task extends RuntimeRequirement>(task: Readonly<Task>, options?: Readonly<RuntimeManagerAcquireOptions>): Promise<RuntimeLease>;
+    canAcquire<Task extends RuntimeCapacityRequirement>(task: Readonly<Task>): boolean;
+    cleanupAll(): Promise<void>;
+    getGraphFailure(graphKey: string): string | null;
+    getGraph(graphKey: string): null | RuntimeManagerGraph;
+    getStats(): RuntimeManagerGraphStats[];
+    markGraphFailed(graphKey: string, message: string): void;
+    release(lease: null | RuntimeLease | undefined, options?: Readonly<RuntimeManagerReleaseOptions>): Promise<void>;
+}
+export declare function createRuntimeManager({ productDir, graphs, lifecycle, runtimeOptions, }: Readonly<CreateRuntimeManagerOptions>): RuntimeManager;
+export {};

package/dist/environment/runtime-manager.js

@@ -0,0 +1 @@
+import x from"fs";import S from"path";import{buildRuntimeIds as A}from"../domain/runtime-identity.js";import{formatError as y}from"../kernel/error-serialization.js";import{cleanupRuntimeInstanceContext as K,createRuntimeInstanceContext as T,ensureRuntimeInstanceReady as $}from"./runtime-contexts.js";import{timeOperation as D}from"../evidence/operation-timings.js";import{createReadyEnvironment as E}from"./ready-environment.js";export function createRuntimeManager({productDir:t,graphs:a,lifecycle:n,runtimeOptions:r={}}){const i=new Map(a.map(e=>[e.key,e])),c=new Map,s=new Map,u=H(a),f=new Map;let C=1;return{canAcquire(e){if(f.has(e.graphKey))return!1;const o=w(c,i,e);return j(s,v(e))?P(o,e,u)!==null:!1},async acquire(e,o={}){const m=w(c,i,e);if(n.isStopRequested())throw n.signal.reason||new Error("testkit run interrupted");const{leaseId:p,slot:g}=await G(r,o,"testkit.runtime.slot_claim",{summary:"claim runtime slot",scope:{graphKey:e.graphKey,taskId:e.id,serviceName:e.serviceName||null,targetName:e.targetName||null},metadata:{decision:"claim",lockCount:v(e).length.toString(),resourceCost:d(e).toString()}},()=>{const l=`lease-${e.id.toString()}-${C.toString()}`;if(C+=1,!B(s,v(e),l))throw new Error(`Task ${e.id.toString()} was claimed before its locks were available`);const h=q(m,e,u);if(!h)throw k(s,v(e),l),new Error(`Task ${e.id.toString()} was claimed before runtime capacity was available`);return{leaseId:l,slot:h}});try{const l=await F(g,t,e,n,r,o);n.signal.throwIfAborted();const h=S.join(l.runtimeDir,"leases",p);return x.mkdirSync(h,{recursive:!0}),{...E(l,{leaseId:p,leaseDir:h}),lockNames:v(e),resourceCost:d(e),slot:g,context:l}}catch(l){throw I(g,d(e)),k(s,v(e),p),U({leaseDir:S.join(g.context?.runtimeDir||t,"leases",p)}),g.context||N(g,u),await R(g,n,u),n.isStopRequested()||M(f,e.graphKey,y(l)),l}},async release(e,o={}){e?.slot&&(o.invalidate&&(e.slot.draining=!0),e.releaseState||(e.releaseState={locks:!1,runtimeSlot:!1,leaseDir:!1}),e.releaseState.locks||(k(s,e.lockNames,e.leaseId),e.releaseState.locks=!0),e.releaseState.runtimeSlot||(I(e.slot,e.resourceCost),e.releaseState.runtimeSlot=!0),e.releaseState.leaseDir||(U(e),e.releaseState.leaseDir=!0),e.released=!0,e.slot.draining&&e.slot.activeLeaseCount===0&&await R(e.slot,n,u))},async cleanupAll(){const e=[];for(const o of c.values())for(const m of o.slots){m.draining=!0;try{await R(m,n,u)}catch(p){e.push({slot:m,error:p})}}if(e.length>0)throw new AggregateError(e.map(o=>o.error),`Failed to clean up ${e.length.toString()} runtime ${e.length===1?"slot":"slots"}: ${e.map(o=>`${o.slot.runtimeId}: ${y(o.error)}`).join("; ")}`)},getStats(){return[...c.values()].map(e=>({graphKey:e.slots[0]?.graph.key||null,targetNames:[...e.slots.at(0)?.graph.targetNames??[]],maxConcurrentTasks:Number.isFinite(e.slots[0]?.graph.maxConcurrentTasks)?e.slots[0]?.graph.maxConcurrentTasks??null:null,runtimeCount:e.slots.length,runtimes:e.slots.map(o=>({runtimeId:o.runtimeId,peakLeaseCount:o.peakLeaseCount,peakResourceUnits:o.peakResourceUnits,resourceReservations:o.resourceReservations.map(m=>({...m}))})),resourceBudgets:[...u.values()].filter(o=>e.slots.some(m=>m.graph.resourceReservations.some(p=>p.key===o.key))).map(o=>({key:o.key,capacity:o.capacity,reserved:o.reserved,available:o.available,active:o.active,peakActive:o.peakActive}))})).sort((e,o)=>(e.graphKey||"").localeCompare(o.graphKey||""))},getGraphFailure(e){return f.get(e)??null},getGraph(e){return i.get(e)||null},markGraphFailed(e,o){M(f,e,o)}}}function w(t,a,n){const r=t.get(n.graphKey);if(r)return r;const i=a.get(n.graphKey);if(!i)throw new Error(`Unknown graph "${n.graphKey}"`);const s={slots:A(i.instanceCount).map(u=>({graph:i,runtimeId:u,context:null,activeLeaseCount:0,activeResourceUnits:0,resourceReservations:[],peakLeaseCount:0,peakResourceUnits:0,draining:!1}))};return t.set(n.graphKey,s),s}function q(t,a,n){const r=d(a),i=t.slots.filter(s=>!s.draining);if(i.length===0)return null;const c=[...i].filter(s=>L(s,r)&&b(s,n)).sort((s,u)=>s.activeResourceUnits-u.activeResourceUnits||s.activeLeaseCount-u.activeLeaseCount||s.runtimeId.localeCompare(u.runtimeId)).at(0);return c?(O(c,n),c.activeLeaseCount+=1,c.activeResourceUnits+=r,c.peakLeaseCount=Math.max(c.peakLeaseCount,c.activeLeaseCount),c.peakResourceUnits=Math.max(c.peakResourceUnits,c.activeResourceUnits),c):null}function I(t,a){t.activeLeaseCount=Math.max(0,t.activeLeaseCount-1),t.activeResourceUnits=Math.max(0,t.activeResourceUnits-a)}async function F(t,a,n,r,i,c={}){t.context||(t.context=T(t.runtimeId,t.graph,a),r.trackGraphContext(t.context));const s=i.operationTimingRegistry||null,u=s?.start({name:"testkit.runtime.ensure",kind:"runtime",summary:"ensure runtime instance ready",parentId:c.operationTimingParentId||null,scope:{graphKey:t.graph.key,runtimeId:t.runtimeId,serviceName:n.serviceName,targetName:n.targetName}})??null;try{await $(t.context,n.startApplicationServices,r,i),s?.finish(u,{status:"passed"})}catch(f){throw s?.finish(u,{status:"failed",error:y(f)}),f}return t.context}function G(t,a,n,r,i){return D(t.operationTimingRegistry||null,{name:n,kind:"runtime",summary:r.summary||null,parentId:a.operationTimingParentId||null,scope:r.scope||null,metadata:r.metadata||null},i)}async function R(t,a,n){!t.context||t.activeLeaseCount>0||(await K(t.context,a),N(t,n),t.context=null,t.draining=!1)}function B(t,a,n){const r=[...new Set(a)].sort();for(const i of r)if(t.has(i))return!1;for(const i of r)t.set(i,n);return!0}function j(t,a){return[...new Set(a)].every(n=>!t.has(n))}function P(t,a,n){const r=d(a);return t.slots.find(i=>!i.draining&&L(i,r)&&b(i,n))||null}function L(t,a){return t.activeResourceUnits+a<=t.graph.maxConcurrentTasks}function H(t){const a=new Map;for(const n of t)for(const r of n.resourceReservations){const i=a.get(r.key)||{key:r.key,capacity:r.capacity||0,reserved:r.reserved||0,available:r.available||Math.max(0,(r.capacity||0)-(r.reserved||0)),active:0,peakActive:0};i.capacity=Math.max(i.capacity,r.capacity||0),i.reserved=Math.max(i.reserved,r.reserved||0),i.available=Math.max(0,i.capacity-i.reserved),a.set(r.key,i)}return a}function b(t,a){return t.resourceReservations.length>0?!0:t.graph.resourceReservations.every(n=>{const r=a.get(n.key);return r?r.active+n.perRuntime<=r.available:!0})}function O(t,a){if(t.resourceReservations.length>0)return;const n=[];for(const r of t.graph.resourceReservations){const i=a.get(r.key);i&&(i.active+=r.perRuntime,i.peakActive=Math.max(i.peakActive,i.active),n.push({key:r.key,units:r.perRuntime,services:r.services}))}t.resourceReservations=n}function N(t,a){for(const n of t.resourceReservations){const r=a.get(n.key);r&&(r.active=Math.max(0,r.active-n.units))}t.resourceReservations=[]}function k(t,a,n){for(const r of[...new Set(a)].sort())t.get(r)===n&&t.delete(r)}function M(t,a,n){!a||t.has(a)||t.set(a,n)}function v(t){return t.locks||[]}function d(t){return t.resourceCost??1}function U(t){t?.leaseDir&&x.rmSync(t.leaseDir,{recursive:!0,force:!0})}

package/dist/environment/runtime-planning.d.ts

@@ -0,0 +1,16 @@
+import type { NormalizedServiceConfig } from "../config/loader/index.js";
+import type { DesiredRuntimeGraph } from "./planning-types.js";
+import { resolveRuntimeInstanceConfigs } from "./template.js";
+import { resolveRuntimeConfigs } from "../config/loader/dependencies.js";
+import type { RuntimeGraph, RuntimeSelection, RuntimeServiceSpec } from "./planning-types.js";
+export interface RuntimePlanning {
+    collectDesiredRuntimeGraphs: typeof collectDesiredRuntimeGraphs;
+    resolveRuntimeInstanceConfigs: typeof resolveRuntimeInstanceConfigs;
+    buildRuntimeGraphs: typeof buildRuntimeGraphs;
+    resolveRuntimeConfigs: typeof resolveRuntimeConfigs;
+    buildGraphDirName: typeof buildGraphDirName;
+}
+export declare const runtimePlanning: RuntimePlanning;
+export declare function buildRuntimeGraphs<Config extends RuntimeServiceSpec>(servicePlans: readonly RuntimeSelection<Config>[]): RuntimeGraph<Config>[];
+export declare function buildGraphDirName(runtimeNames: readonly string[]): string;
+export declare function collectDesiredRuntimeGraphs(allConfigs?: readonly NormalizedServiceConfig[]): DesiredRuntimeGraph[];

package/dist/environment/runtime-planning.js

@@ -0,0 +1 @@
+import{resolveRuntimeInstanceConfigs as p}from"./template.js";import{buildGraphResourceReservations as g}from"../database/runtime-reservations.js";import{resolveRuntimeConfigs as m}from"../config/loader/dependencies.js";export const runtimePlanning=Object.freeze({collectDesiredRuntimeGraphs,resolveRuntimeInstanceConfigs:p,buildRuntimeGraphs,resolveRuntimeConfigs:m,buildGraphDirName});export function buildRuntimeGraphs(r){const s=[],a=new Map;for(const e of r){const n=a.get(e.runtimeKey);if(n){n.targetNames.push(e.config.name),n.instanceCount=Math.max(n.instanceCount,e.config.testkit.runtime.instances),n.maxConcurrentTasks=Math.min(n.maxConcurrentTasks,u(e.runtimeConfigs));continue}const i={key:e.runtimeKey,runtimeNames:e.runtimeNames,runtimeConfigs:e.runtimeConfigs,targetNames:[e.config.name],dirName:buildGraphDirName(e.runtimeNames),instanceCount:e.config.testkit.runtime.instances,maxConcurrentTasks:u(e.runtimeConfigs),resourceReservations:g(e.runtimeConfigs)};s.push(i),a.set(e.runtimeKey,i)}const t=s.sort((e,n)=>e.dirName.localeCompare(n.dirName)),o=Math.max(1,...t.map(e=>e.instanceCount));return t.map((e,n)=>({...e,portNamespaceIndex:n,portNamespaceStride:o}))}export function buildGraphDirName(r){const s=r.map(f).join("__");return s.length>0?s:"graph"}function f(r){return r.toLowerCase().replace(/[^a-z0-9]+/g,"_").replace(/^_+|_+$/g,"")||"svc"}function u(r){return r.reduce((s,a)=>Math.min(s,a.testkit.runtime.maxConcurrentTasks),Number.POSITIVE_INFINITY)}export function collectDesiredRuntimeGraphs(r=[]){const s=new Map(r.map(t=>[t.name,t])),a=new Map;for(const t of r){const e=m(t,s).map(c=>c.name).sort(),n=e.join("|"),i=a.get(n);if(i){i.targetNames.push(t.name),i.targetNames.sort(),i.instanceCount=Math.max(i.instanceCount,t.testkit.runtime.instances);continue}a.set(n,{key:n,dirName:buildGraphDirName(e),runtimeNames:e,targetNames:[t.name],instanceCount:t.testkit.runtime.instances})}return[...a.values()].sort((t,o)=>t.dirName.localeCompare(o.dirName))}