@gfdelarue/testkit 0.3.0

package/dist/evidence/reporting-types.d.ts

@@ -0,0 +1,330 @@
+import type { NormalizedArtifactArchiveConfig } from "./artifact-config.js";
+import type { EngineId, PublicTestType, RunnerProfileId } from "../domain/identifiers.js";
+import type { SerializedError } from "../kernel/error-serialization.js";
+export type ReportingRecord = Record<string, unknown>;
+export interface ReportingFailureRequest extends ReportingRecord {
+    method?: string;
+    path?: string;
+    requestId?: string;
+}
+export interface ReportingFailureResponse extends ReportingRecord {
+    bodyPreview?: string;
+    contentType?: string;
+    status?: number | string;
+}
+export interface ReportingFailureLocation extends ReportingRecord {
+    column?: number;
+    line?: number;
+    path?: string;
+}
+export interface ReportingFailureDetail extends ReportingRecord {
+    key?: string;
+    kind?: string;
+    location?: ReportingFailureLocation;
+    message?: string;
+    request?: ReportingFailureRequest;
+    response?: ReportingFailureResponse;
+    stack?: string;
+    title: string;
+}
+export interface ReportingArtifactReference extends ReportingRecord {
+    contentType?: null | string;
+    kind?: null | string;
+    name: string;
+    path: string;
+    summary?: null | string;
+}
+export interface ReportingRuntimeBatch extends ReportingRecord {
+    fileCount?: number;
+    files?: string[];
+    id?: string;
+    index?: number;
+}
+export interface ReportingRuntimeReset extends ReportingRecord {
+    position?: string;
+    reason?: string;
+    runtimeIsolation?: string;
+    trigger?: string;
+}
+export interface RunArtifactFile extends ReportingRecord {
+    artifacts?: ReportingArtifactReference[];
+    blockedByRuntime?: boolean;
+    durationMs?: null | number;
+    error?: null | string;
+    failed?: boolean;
+    failureDetails?: ReportingFailureDetail[];
+    infraFailed?: boolean;
+    path: string;
+    reason?: null | string;
+    runtimeBatch?: null | ReportingRuntimeBatch;
+    runtimeIsolation?: null | string;
+    runtimeResets?: ReportingRuntimeReset[];
+    status: string;
+}
+export interface ReportingDiagnostic extends ReportingRecord {
+    code: string;
+    message: string;
+    service?: string;
+    suite?: string;
+}
+export interface RunArtifactSuite extends ReportingRecord {
+    completedFileCount?: number;
+    diagnostics?: ReportingDiagnostic[];
+    engineId: EngineId;
+    failed?: boolean;
+    failedFileCount?: number;
+    fileCount?: number;
+    files?: RunArtifactFile[];
+    name: string;
+    passedFileCount?: number;
+    profileId: RunnerProfileId;
+    skippedFileCount?: number;
+    testType: PublicTestType | "scenario";
+}
+export interface RunServiceResult extends ReportingRecord {
+    failed: boolean;
+    name: string;
+    skipped: boolean;
+    suites: RunArtifactSuite[];
+    blockedByRuntime?: boolean;
+    completedFileCount: number;
+    completedSuiteCount: number;
+    dbBackend?: null | string;
+    diagnostics?: ReportingDiagnostic[];
+    durationMs: number;
+    errorDetails?: ReportingRecord[];
+    errors: string[];
+    failedFileCount: number;
+    failedSuiteCount: number;
+    infraFailed?: boolean;
+    notRunFileCount: number;
+    passedFileCount: number;
+    skippedFileCount: number;
+    skippedSuiteCount: number;
+    suiteCount: number;
+    totalFileCount: number;
+    totalTaskDurationMs: number;
+}
+export interface RunArtifactService extends ReportingRecord {
+    name: string;
+    suites: RunArtifactSuite[];
+}
+export interface ReportedRunService extends RunServiceResult {
+    blockedByRuntime: boolean;
+    infraFailed: boolean;
+}
+export interface ReportingServiceLogReference extends ReportingRecord {
+    path: string;
+    runtimeLabel: string;
+    serviceName: string;
+}
+export interface ReportingSetupLogReference extends ReportingRecord {
+    path: string;
+    runtimeLabel?: string;
+    serviceName?: string;
+    stage?: string;
+}
+export interface ReportingSetupOperation extends ReportingRecord {
+    durationMs?: null | number;
+    error?: null | string;
+    logRef?: null | ReportingSetupLogReference;
+    serviceName: string;
+    stage: string;
+    startedAt?: string;
+    status: string;
+    summary?: null | string;
+}
+export interface ReportingOperationTimingInput extends ReportingRecord {
+    durationMs?: null | number;
+    error?: null | string;
+    finishedAt?: null | string;
+    id?: null | string;
+    kind?: string;
+    logRefs?: unknown[];
+    message?: null | string;
+    metadata?: ReportingRecord;
+    name?: string;
+    parentId?: null | string;
+    scope?: ReportingRecord;
+    source?: string;
+    startedAt?: null | string;
+    status?: string;
+    summary?: null | string;
+    updatedAt?: null | string;
+}
+export interface ReportingOperationTiming extends ReportingRecord {
+    durationMs: null | number;
+    error: null | string;
+    finishedAt: null | string;
+    id: null | string;
+    kind: string;
+    logRefs: unknown[];
+    message: null | string;
+    metadata: ReportingRecord;
+    name: string;
+    parentId: null | string;
+    scope: ReportingRecord;
+    source: string;
+    startedAt: null | string;
+    status: string;
+    summary: null | string;
+    updatedAt: null | string;
+}
+export interface ReportingGitRepository {
+    host: string;
+    name: string;
+    owner: string;
+}
+export interface ReportingRunGitMetadata extends ReportingRecord {
+    branch: null | string;
+    commitSha: null | string;
+    dirty: boolean;
+    pullRequest: null | number;
+    pullRequestHeadSha: null | string;
+    repository: null | ReportingGitRepository;
+}
+export interface ReportingMetadata {
+    git: ReportingRecord & {
+        branch?: null | string;
+        commitSha?: null | string;
+        dirty?: boolean;
+        pullRequest?: null | number;
+        pullRequestHeadSha?: null | string;
+        repository?: null | ReportingGitRepository;
+    };
+    host?: ReportingRecord;
+    testkitVersion: string;
+}
+export interface ReportingExecution {
+    fileTimeoutSeconds: number;
+    taskConcurrency: number;
+}
+export interface ReportingSuiteSelector extends ReportingRecord {
+    raw: string;
+}
+export interface RunArtifactRun extends ReportingRecord {
+    durationMs?: null | number;
+    types?: string[];
+    finishedAt: null | string;
+    id: null | string;
+    startedAt: string;
+    status: string;
+}
+export interface RunArtifactDocument extends ReportingRecord {
+    generatedAt?: string;
+    summary?: RunArtifactSummary;
+    schemaVersion: 19;
+    archive?: ReportingRecord;
+    finalizationFailure?: SerializedError;
+    logs?: {
+        services?: ReportingServiceLogReference[];
+        setup?: ReportingSetupLogReference[];
+    };
+    run: RunArtifactRun;
+    services: RunArtifactService[];
+    setup?: {
+        operations?: ReportingSetupOperation[];
+    };
+}
+export interface ReportedRunArtifact extends RunArtifactDocument {
+    archive: {
+        declaredEnvironmentKeys: string[];
+        request: NormalizedArtifactArchiveConfig;
+    };
+    generatedAt: string;
+    git: ReportingRunGitMetadata;
+    logs: {
+        services: ReportingServiceLogReference[];
+        setup: ReportingSetupLogReference[];
+    };
+    product: {
+        directory: string;
+        name: string;
+    };
+    run: RunArtifactRun & {
+        dbBackend: null | string;
+        durationMs: null | number;
+        fileNames: string[];
+        fileTimeoutSeconds: number;
+        runtimeInstanceCount: number;
+        runtimeStats: unknown[];
+        serviceFilter: null | string;
+        suiteSelectors: string[];
+        testkitVersion: string;
+        types: string[];
+        workerCount: number;
+        workers: number;
+    };
+    schemaVersion: 19;
+    services: ReportedRunService[];
+    setup: {
+        operations: ReportingSetupOperation[];
+    };
+    source: "testkit";
+    summary: RunArtifactSummary;
+    timings: {
+        operations: ReportingOperationTiming[];
+    };
+}
+export interface ReportingServiceSummary {
+    blockedByRuntime: number;
+    failed: number;
+    infraFailed: number;
+    passed: number;
+    skipped: number;
+    total: number;
+}
+export interface ReportingSuiteSummary {
+    completed: number;
+    failed: number;
+    passed: number;
+    skipped: number;
+    total: number;
+}
+export interface ReportingFileSummary {
+    blockedByRuntime: number;
+    cancelled: number;
+    failed: number;
+    infraFailed: number;
+    interrupted: number;
+    notRun: number;
+    passed: number;
+    skipped: number;
+    total: number;
+}
+export interface RunArtifactSummary extends ReportingRecord {
+    diagnostics?: ReportingDiagnostic[];
+    files: ReportingFileSummary;
+    services: ReportingServiceSummary;
+    suites: ReportingSuiteSummary;
+}
+export interface BuildRunArtifactOptions {
+    archiveConfig?: NormalizedArtifactArchiveConfig | null;
+    declaredEnvironmentKeys?: readonly string[];
+    execution: ReportingExecution;
+    fileNames: readonly string[];
+    finishedAt: null | number;
+    metadata: ReportingMetadata;
+    operationTimings?: readonly ReportingOperationTimingInput[];
+    planning?: null | ReportingRecord;
+    productDir: string;
+    results: readonly RunServiceResult[];
+    runId?: null | string;
+    runInterruptReason?: null | string;
+    runStatus?: null | string;
+    runtimeInstanceCount: number;
+    runtimeStats?: readonly unknown[];
+    serviceFilter: null | string;
+    serviceLogs?: readonly ReportingServiceLogReference[];
+    setupLogs?: readonly ReportingSetupLogReference[];
+    setupOperations?: readonly ReportingSetupOperation[];
+    startedAt: number;
+    suiteSelectors: readonly ReportingSuiteSelector[];
+    summarizeDbBackend: (results: readonly RunServiceResult[]) => unknown;
+    typeValues: readonly string[];
+    workerCount: number;
+}
+export type BuildLiveRunArtifactOptions = Omit<BuildRunArtifactOptions, "finishedAt" | "runStatus"> & {
+    updatedAt: number;
+};
+export declare const DEFAULT_REPORTED_ARCHIVE_CONFIG: NormalizedArtifactArchiveConfig;

package/dist/evidence/reporting-types.js

@@ -0,0 +1 @@
+export const DEFAULT_REPORTED_ARCHIVE_CONFIG={retention:{maxAgeDays:null,maxRuns:null,preserveSuites:[]},publication:null};

package/dist/evidence/reporting.d.ts

@@ -0,0 +1,3 @@
+import { type BuildLiveRunArtifactOptions, type BuildRunArtifactOptions, type ReportedRunArtifact } from "./reporting-types.js";
+export declare function buildRunArtifact({ productDir, runId, results, startedAt, finishedAt, execution, workerCount, runtimeInstanceCount, runtimeStats, typeValues, suiteSelectors, fileNames, serviceFilter, planning, archiveConfig, declaredEnvironmentKeys, metadata, summarizeDbBackend, serviceLogs, setupLogs, setupOperations, operationTimings, runInterruptReason, runStatus, }: BuildRunArtifactOptions): ReportedRunArtifact;
+export declare function buildLiveRunArtifact({ productDir, runId, results, startedAt, updatedAt, execution, workerCount, runtimeInstanceCount, runtimeStats, typeValues, suiteSelectors, fileNames, serviceFilter, planning, archiveConfig, declaredEnvironmentKeys, metadata, summarizeDbBackend, serviceLogs, setupLogs, setupOperations, operationTimings, }: BuildLiveRunArtifactOptions): ReportedRunArtifact;

package/dist/evidence/reporting.js

@@ -0,0 +1 @@
+import Z from"path";import{DEFAULT_REPORTED_ARCHIVE_CONFIG as $}from"./reporting-types.js";export function buildRunArtifact({productDir:n,runId:e=null,results:i,startedAt:l,finishedAt:s,execution:o,workerCount:a,runtimeInstanceCount:d,runtimeStats:m,typeValues:g,suiteSelectors:k,fileNames:F,serviceFilter:C,planning:f=null,archiveConfig:S=null,declaredEnvironmentKeys:h=[],metadata:c,summarizeDbBackend:R,serviceLogs:y=[],setupLogs:b=[],setupOperations:v=[],operationTimings:D=[],runInterruptReason:M=null,runStatus:x=null}){const u=i.filter(t=>!t.skipped),E=u.filter(q),A=u.filter(t=>t.failed),B=u.filter(t=>t.infraFailed),z=u.filter(t=>t.blockedByRuntime),N=u.filter(t=>ee(t)),w=se(u),V=te(u),H=r(u,"totalFileCount"),_=r(u,"passedFileCount"),L=r(u,"failedFileCount"),P=r(u,"skippedFileCount"),j=r(u,"notRunFileCount"),I=p(u,t=>t.status==="cancelled"),O=p(u,t=>t.status==="interrupted"),G=Math.max(0,j-I-O),J=p(u,t=>t.infraFailed===!0),K=p(u,t=>t.blockedByRuntime===!0),T=R(i),U=typeof T=="string"?T:null,Q=new Date(s??Date.now()).toISOString(),W=s===null?null:new Date(s).toISOString(),X=s===null?null:s-l,Y=S??$;return{schemaVersion:19,source:"testkit",generatedAt:Q,product:{name:Z.basename(n),directory:n},git:{branch:c.git.branch??null,commitSha:c.git.commitSha??null,dirty:c.git.dirty===!0,pullRequest:c.git.pullRequest??null,pullRequestHeadSha:c.git.pullRequestHeadSha??null,repository:c.git.repository??null},host:c.host,run:{id:e,status:x||(A.length>0||B.length>0?"failed":"passed"),startedAt:new Date(l).toISOString(),finishedAt:W,durationMs:X,workers:o.taskConcurrency,fileTimeoutSeconds:o.fileTimeoutSeconds,workerCount:a,runtimeInstanceCount:d,runtimeStats:[...m??[]],dbBackend:U,types:[...g],suiteSelectors:k.map(t=>t.raw),fileNames:[...F],serviceFilter:C,testkitVersion:c.testkitVersion,...M===null?{}:{interruptReason:M}},archive:{request:Y,declaredEnvironmentKeys:[...new Set(h)].sort()},...f?{planning:f}:{},summary:{services:{total:u.length,passed:N.length,failed:A.length,infraFailed:B.length,blockedByRuntime:z.length,skipped:E.length},suites:V,files:{total:H,passed:_,failed:L,skipped:P,notRun:G,cancelled:I,interrupted:O,infraFailed:J,blockedByRuntime:K},...w.length>0?{diagnostics:w}:{}},logs:{services:[...y],setup:[...b]},setup:{operations:[...v]},timings:{operations:oe(D)},services:i.map(t=>({name:t.name,failed:t.failed,infraFailed:t.infraFailed===!0,blockedByRuntime:t.blockedByRuntime===!0,skipped:t.skipped,suiteCount:t.suiteCount,completedSuiteCount:t.completedSuiteCount,skippedSuiteCount:t.skippedSuiteCount,failedSuiteCount:t.failedSuiteCount,totalFileCount:t.totalFileCount,completedFileCount:t.completedFileCount,passedFileCount:t.passedFileCount,failedFileCount:t.failedFileCount,skippedFileCount:t.skippedFileCount,notRunFileCount:t.notRunFileCount,durationMs:t.durationMs,totalTaskDurationMs:t.totalTaskDurationMs,dbBackend:t.dbBackend,suites:t.suites,errors:t.errors,...t.diagnostics&&t.diagnostics.length>0?{diagnostics:t.diagnostics}:{},...t.errorDetails&&t.errorDetails.length>0?{errorDetails:t.errorDetails}:{}}))}}export function buildLiveRunArtifact({productDir:n,runId:e=null,results:i,startedAt:l,updatedAt:s,execution:o,workerCount:a,runtimeInstanceCount:d,runtimeStats:m,typeValues:g,suiteSelectors:k,fileNames:F,serviceFilter:C,planning:f=null,archiveConfig:S=null,declaredEnvironmentKeys:h=[],metadata:c,summarizeDbBackend:R,serviceLogs:y=[],setupLogs:b=[],setupOperations:v=[],operationTimings:D=[]}){return{...buildRunArtifact({productDir:n,runId:e,results:i,startedAt:l,finishedAt:null,execution:o,workerCount:a,runtimeInstanceCount:d,runtimeStats:m,typeValues:g,suiteSelectors:k,fileNames:F,serviceFilter:C,planning:f,archiveConfig:S,declaredEnvironmentKeys:h,metadata:c,summarizeDbBackend:R,serviceLogs:y,setupLogs:b,setupOperations:v,operationTimings:D,runStatus:"running"}),generatedAt:new Date(s).toISOString()}}function q(n){return!n.skipped&&!n.failed&&n.skippedSuiteCount>0&&n.skippedSuiteCount===n.suiteCount&&n.notRunFileCount===0}function ee(n){return!n.failed&&!n.infraFailed&&!q(n)&&n.notRunFileCount===0}function p(n,e){let i=0;for(const l of n)for(const s of l.suites)for(const o of s.files??[])e(o)&&(i+=1);return i}function te(n){const e={total:0,completed:0,passed:0,failed:0,skipped:0};for(const i of n){const l=i.suites,s=i.suiteCount;if(l.length===0){const o=ne(i,s);e.total+=o.total,e.completed+=o.completed,e.passed+=o.passed,e.failed+=o.failed,e.skipped+=o.skipped;continue}e.total+=s;for(const o of l){const a=ie(o);a==="passed"?(e.completed+=1,e.passed+=1):a==="failed"?(e.completed+=1,e.failed+=1):a==="skipped"&&(e.completed+=1,e.skipped+=1)}}return e}function ne(n,e){const i=n.failedSuiteCount,l=n.skippedSuiteCount,s=n.completedSuiteCount;return{total:e,completed:s,passed:Math.max(0,s-i-l),failed:i,skipped:l}}function ie(n){const e=n.files??[],i=e.length,l=Math.max(n.fileCount??0,i),s=e.length>0?e.filter(d=>d.status==="failed"||d.failed===!0).length:n.failedFileCount??0,o=e.length>0?e.filter(d=>d.status==="skipped").length:n.skippedFileCount??0,a=e.length>0?e.filter(d=>d.status==="passed").length:n.passedFileCount??0;return s>0||n.failed===!0?"failed":l>0&&o>=l?"skipped":l>0&&a+o>=l?"passed":"pending"}function r(n,e){return n.reduce((i,l)=>i+l[e],0)}function se(n){const e=[],i=new Set,l=s=>{const o=JSON.stringify(s);i.has(o)||(i.add(o),e.push(s))};for(const s of n){const o=s.diagnostics??[];for(const a of o)l({...a,service:a.service||s.name});if(!(o.length>0))for(const a of s.suites)for(const d of a.diagnostics??[])l({...d,service:d.service||s.name,suite:d.suite||a.name})}return e}function oe(n){return n.map(e=>({id:e.id||null,source:e.source||"testkit",name:e.name||"operation",kind:e.kind||"operation",summary:e.summary||null,scope:e.scope?{...e.scope}:{},parentId:e.parentId||null,status:e.status||"unknown",startedAt:e.startedAt||null,updatedAt:e.updatedAt||null,finishedAt:e.finishedAt||null,durationMs:e.durationMs!==null&&e.durationMs!==void 0&&Number.isFinite(e.durationMs)?Math.max(0,Math.round(e.durationMs)):null,error:e.error||null,message:e.message||null,logRefs:(e.logRefs??[]).map(i=>le(i)?{...i}:i),metadata:e.metadata?{...e.metadata}:{}}))}function le(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}

package/dist/evidence/secure-file-copy.d.ts

@@ -0,0 +1,24 @@
+export declare const MAX_PERSISTED_FILE_ARTIFACT_BYTES: number;
+export interface SecureFileCopyOptions {
+    /**
+     * Test and narrower-call-site seam. Values may lower, but never raise, the
+     * product-wide artifact ceiling.
+     */
+    maxBytes?: number;
+    /** Invoked after the source handle and its identity have been verified. */
+    onSourceOpened?: () => void;
+    /** Describes a narrowed caller-owned byte limit in diagnostics. */
+    sizeLimitDescription?: string;
+    /** When present, the source's canonical path must remain below this root. */
+    sourceRoot?: string;
+}
+export interface SecureFileCopyResult {
+    readonly canonicalSourcePath: string;
+    readonly sizeBytes: number;
+}
+/**
+ * Copies one regular file through a single verified source handle. The source
+ * must remain the same file for the whole read, and a failed copy never leaves
+ * a partial destination behind.
+ */
+export declare function copyRegularFileSecurely(sourcePath: string, destinationPath: string, options?: Readonly<SecureFileCopyOptions>): SecureFileCopyResult;

package/dist/evidence/secure-file-copy.js

@@ -0,0 +1 @@
+import{isPathWithin as m}from"../process/files/paths.js";import n from"node:fs";import w from"node:path";import{readOnlyNoFollowOpenFlags as $,sameFileSnapshot as b,samePathAndHandleFileSnapshot as E}from"../process/files/file-snapshot.js";export const MAX_PERSISTED_FILE_ARTIFACT_BYTES=512*1024*1024;const D=64*1024;export function copyRegularFileSecurely(t,e,r={}){const i=w.resolve(t),u=w.resolve(e),o=Math.min(r.maxBytes??MAX_PERSISTED_FILE_ARTIFACT_BYTES,MAX_PERSISTED_FILE_ARTIFACT_BYTES),c=r.sizeLimitDescription?.trim()??"file-artifact limit",l=r.sourceRoot===void 0?null:C(r.sourceRoot,"artifact source root"),f=O(i),y=n.realpathSync.native(i);if(l!==null&&!m(l,y))throw new Error(`Artifact source ${JSON.stringify(i)} escapes its required source root`);let p=!1,a=null,s=null;try{s=n.openSync(i,$(process.platform,n.constants));const S=n.fstatSync(s,{bigint:!0});I(f,S,i),J(S.size,o,i,c),r.onSourceOpened?.(),a=n.openSync(u,n.constants.O_CREAT|n.constants.O_EXCL|n.constants.O_WRONLY,384),p=!0;const d=N(s,a,o,i,c);n.fsyncSync(a);const g=n.fstatSync(s,{bigint:!0});if(L(S,g,i),BigInt(d)!==S.size)throw new Error(`Artifact source ${JSON.stringify(i)} changed size while it was copied`);return R(i,y,f,g,l),F(a),a=null,F(s),s=null,{canonicalSourcePath:y,sizeBytes:d}}catch(S){throw h(a),a=null,h(s),s=null,p&&n.rmSync(u,{force:!0}),S}finally{h(a),h(s)}}function N(t,e,r,i,u){const o=Buffer.allocUnsafe(D);let c=0;for(;;){const l=n.readSync(t,o,0,o.byteLength,null);if(l===0)return c;if(c+=l,c>r)throw A(i,r,u);let f=0;for(;f<l;){const y=n.writeSync(e,o,f,l-f,null);if(y<=0)throw new Error(`Could not make progress while persisting artifact source ${JSON.stringify(i)}`);f+=y}}}function R(t,e,r,i,u){const o=O(t),c=n.realpathSync.native(t);if(c!==e||!b(r,o)||!E(o,i,process.platform)||u!==null&&!m(u,c))throw new Error(`Artifact source ${JSON.stringify(t)} was replaced while it was copied`)}function I(t,e,r){if(!e.isFile()||!E(t,e,process.platform))throw new Error(`Artifact source ${JSON.stringify(r)} changed while it was copied`)}function O(t){let e;try{e=n.lstatSync(t,{bigint:!0})}catch(r){throw new Error(`Artifact source file does not exist or cannot be inspected: ${t}`,{cause:r})}if(e.isSymbolicLink())throw new Error(`Artifact source ${JSON.stringify(t)} must not be a symbolic link`);if(!e.isFile())throw new Error(`Artifact source ${JSON.stringify(t)} must be a regular file`);return e}function L(t,e,r){if(!e.isFile()||!b(t,e))throw new Error(`Artifact source ${JSON.stringify(r)} changed while it was copied`)}function C(t,e){const r=w.resolve(t),i=n.lstatSync(r,{bigint:!0});if(i.isSymbolicLink()||!i.isDirectory())throw new Error(`${e} must be a real directory, not a symbolic link`);return n.realpathSync.native(r)}function J(t,e,r,i){if(t>BigInt(e))throw A(r,e,i)}function A(t,e,r){return new Error(`Artifact source ${JSON.stringify(t)} exceeds the ${e.toString()} byte ${r}`)}function F(t){n.closeSync(t)}function h(t){if(t!==null)try{n.closeSync(t)}catch{}}

package/dist/evidence/setup-progress.d.ts

@@ -0,0 +1,63 @@
+export interface StepServiceIdentity {
+    name: string;
+    runtimeLabel?: string | null;
+}
+export interface StepLogRecord {
+    path: string;
+    stage: string;
+    write(chunk: string): void;
+}
+export interface StepLogRegistry {
+    ensureSetupLogRecord(config: Readonly<StepServiceIdentity>, stage: string): StepLogRecord;
+}
+export type SetupOperationLogRegistry = StepLogRegistry;
+export interface SetupOperationLogReference {
+    [key: string]: unknown;
+    path: string;
+    stage: string;
+}
+export interface SetupOperationStartInput {
+    config: Readonly<StepServiceIdentity>;
+    kind?: string;
+    parentId?: string | null;
+    recordLog?: boolean;
+    stage: string;
+    summary?: string | null;
+}
+export type SetupOperationCachedInput = Omit<SetupOperationStartInput, "recordLog">;
+export interface SetupOperationFinishInput {
+    error?: unknown;
+    status?: string;
+    summary?: string | null;
+}
+export interface SetupOperationSnapshot {
+    [key: string]: unknown;
+    durationMs: number | null;
+    error: string | null;
+    finishedAt: string | null;
+    id: string;
+    kind: string;
+    logRef: SetupOperationLogReference | null;
+    parentId: string | null;
+    runtimeLabel: string;
+    serviceName: string;
+    stage: string;
+    startedAt: string;
+    status: string;
+    summary: string | null;
+}
+export interface SetupOperationHandle extends SetupOperationSnapshot {
+    _logRecord: StepLogRecord | null;
+}
+export interface SetupOperationRegistry {
+    finish(target: string | SetupOperationHandle | null | undefined, result?: Readonly<SetupOperationFinishInput>): SetupOperationHandle | null;
+    listOperations(): SetupOperationSnapshot[];
+    recordCached(input: Readonly<SetupOperationCachedInput>): SetupOperationHandle;
+    start(input: Readonly<SetupOperationStartInput>): SetupOperationHandle;
+}
+export type SetupOperationChangeHandler = (operations: readonly SetupOperationSnapshot[]) => void;
+export interface CreateSetupOperationRegistryOptions {
+    logRegistry?: SetupOperationLogRegistry | null;
+    onChange?: SetupOperationChangeHandler | null;
+}
+export declare function createSetupOperationRegistry({ logRegistry, onChange, }?: Readonly<CreateSetupOperationRegistryOptions>): SetupOperationRegistry;

package/dist/evidence/setup-progress.js

@@ -0,0 +1 @@
+const R=String;export function createSetupOperationRegistry({logRegistry:t=null,onChange:h=null}={}){const c=[],m=new Map;let a=1;function f(){h?.(g())}function p({config:e,stage:s,kind:u="setup",summary:l=null,parentId:n=null,recordLog:r=!0}){const i=new Date().toISOString(),d=r&&t?.ensureSetupLogRecord(e,s)||null,o={id:`setup-${a.toString()}`,serviceName:e.name,runtimeLabel:e.runtimeLabel||e.name,stage:s,kind:u,summary:l,parentId:n,status:"running",startedAt:i,finishedAt:null,durationMs:null,error:null,logRef:d?{path:d.path,stage:d.stage}:null,_logRecord:d};return a+=1,c.push(o),m.set(o.id,o),f(),o}function A(e,{status:s="passed",summary:u,error:l=null}={}){const n=typeof e=="string"?m.get(e):e;if(!n)return null;const r=new Date().toISOString();return n.finishedAt=r,n.durationMs=Math.max(0,Date.parse(r)-Date.parse(n.startedAt||r)),n.status=s,u!==void 0&&(n.summary=u),l!==null&&(n.error=R(l)),f(),n}function S({config:e,stage:s,kind:u="setup",summary:l=null,parentId:n=null}){const r=new Date().toISOString(),i={id:`setup-${a.toString()}`,serviceName:e.name,runtimeLabel:e.runtimeLabel||e.name,stage:s,kind:u,summary:l,parentId:n,status:"cached",startedAt:r,finishedAt:r,durationMs:0,error:null,logRef:null,_logRecord:null};return a+=1,c.push(i),m.set(i.id,i),f(),i}function g(){return c.map(b)}return{start:p,finish:A,recordCached:S,listOperations:g}}function b(t){return{id:t.id,serviceName:t.serviceName,runtimeLabel:t.runtimeLabel,stage:t.stage,kind:t.kind,summary:t.summary,parentId:t.parentId,status:t.status,startedAt:t.startedAt,finishedAt:t.finishedAt,durationMs:t.durationMs,error:t.error,logRef:t.logRef}}

package/dist/evidence/step-output.d.ts

@@ -0,0 +1,16 @@
+import type { StepLogRecord } from "./setup-progress.js";
+export interface CaptureStepOutputOptions {
+    livePrefix?: string | null;
+    liveWriter?: ((line: string) => void) | null;
+    logRecord?: StepLogRecord | null;
+}
+interface CapturedStepResult {
+    exitCode: number | null;
+    shortMessage?: string;
+    stdout: string;
+    stderr: string;
+}
+export declare function awaitCapturedResult(result: Readonly<CapturedStepResult>, { livePrefix, liveWriter, logRecord }?: Readonly<CaptureStepOutputOptions>): void;
+export declare function writeCapturedLine(logRecord: StepLogRecord | null, streamName: string, line: string): void;
+export declare function formatCapturedFailure(shortMessage: unknown, stdoutValue: unknown, stderrValue: unknown, fallback: string): string;
+export {};

package/dist/evidence/step-output.js

@@ -0,0 +1,6 @@
+const s=String;export function awaitCapturedResult(t,{livePrefix:n="",liveWriter:o=null,logRecord:r=null}={}){if(u("stdout",t.stdout||"",n,o,r),u("stderr",t.stderr||"",n,o,r),t.exitCode!==0)throw new Error(formatCapturedFailure(t.shortMessage,t.stdout,t.stderr,`Step failed with exit code ${String(t.exitCode)}`))}function u(t,n,o,r,e){for(const i of s(n).split(/\r?\n/).filter(Boolean))writeCapturedLine(e,t,i),r?.(o?`${o} ${i}`:i)}export function writeCapturedLine(t,n,o){t?.write(`${new Date().toISOString()} [${n}] ${o}
+`)}export function formatCapturedFailure(t,n,o,r){const e=[t||r],i=s(n||"").trim(),d=s(o||"").trim();return i&&e.push(`stdout:
+${a(i)}`),d&&e.push(`stderr:
+${a(d)}`),e.join(`
+`)}function a(t,n=80){return s(t||"").split(/\r?\n/).slice(-n).join(`
+`)}

package/dist/evidence/storage-inventory.d.ts

@@ -0,0 +1,27 @@
+export type TestkitStorageClassification = "content_addressed_evidence" | "duplicate_representation" | "evidence_lifecycle_metadata" | "per_run_scratch" | "retained_run_evidence" | "testkit_state";
+export interface TestkitStoragePathClassification {
+    classification: TestkitStorageClassification;
+    duplicateOf?: string;
+    reason: string;
+}
+export interface TestkitStorageEntry extends TestkitStoragePathClassification {
+    bytes: number;
+    linkCount: number;
+    path: string;
+    unique: boolean;
+}
+export interface TestkitStorageInventory {
+    duplicateRepresentations: TestkitStorageEntry[];
+    largestFileLimit: number;
+    largestFiles: TestkitStorageEntry[];
+    root: string;
+    totalFiles: number;
+    totalLogicalBytes: number;
+    totalUniqueBytes: number;
+}
+export interface TestkitStorageInventoryOptions {
+    largestFileLimit?: number;
+    rootRelativePath?: string;
+}
+export declare function collectTestkitStorageInventory(productDir: string, options?: Readonly<TestkitStorageInventoryOptions>): TestkitStorageInventory;
+export declare function classifyTestkitStoragePath(relativePath: unknown): TestkitStoragePathClassification;

package/dist/evidence/storage-inventory.js

@@ -0,0 +1 @@
+import c from"fs";import r from"path";const w=20,F=new Set([".testkit/results/latest.json",".testkit/results/live.json"]);export function collectTestkitStorageInventory(e,t={}){const i=r.resolve(e),{rootDir:s,rootRelativePath:u}=E(i,t.rootRelativePath||".testkit"),l=t.largestFileLimit??w;if(!c.existsSync(s))return W(u,l);const f=[],d=[],b=new Set;let k=0,v=0;for(const o of _(s)){const n=m(r.relative(i,o));if(F.has(n))continue;const a=c.statSync(o,{bigint:!0,throwIfNoEntry:!1});if(a===void 0)continue;const h=classifyTestkitStoragePath(n),g=a.ino?`${String(a.dev)}:${String(a.ino)}`:n,P=!b.has(g);b.add(g);const p=Number(a.size);k+=p,P&&(v+=p);const y={path:n,bytes:p,classification:h.classification,reason:h.reason,linkCount:Number(a.nlink)||1,unique:P};h.duplicateOf&&(y.duplicateOf=h.duplicateOf,d.push(y)),f.push(y)}return f.sort((o,n)=>n.bytes-o.bytes||o.path.localeCompare(n.path)),d.sort((o,n)=>n.bytes-o.bytes||o.path.localeCompare(n.path)),{root:u,largestFileLimit:l,totalFiles:f.length,totalLogicalBytes:k,totalUniqueBytes:v,largestFiles:f.slice(0,l),duplicateRepresentations:d}}export function classifyTestkitStoragePath(e){const t=m(e);return t.endsWith(".b64")?{classification:"duplicate_representation",reason:"base64 representation of a sibling artifact",duplicateOf:t.slice(0,-4)}:t.startsWith(".testkit/results/runs/")?{classification:"retained_run_evidence",reason:"immutable run-addressed Testkit evidence"}:t.startsWith(".testkit/results/objects/")?{classification:"content_addressed_evidence",reason:"deduplicated immutable payload content referenced by run bundles"}:t.startsWith(".testkit/results/publications/")||t.startsWith(".testkit/results/retention/")?{classification:"evidence_lifecycle_metadata",reason:"publication receipt or observable retention decision"}:t.startsWith(".testkit/tmp/")||t.startsWith(".testkit/results/")||t.startsWith(".testkit/run-logs/")||t.startsWith(".testkit/logs/")?{classification:"per_run_scratch",reason:"run-scoped Testkit output or scratch state"}:t.startsWith(".testkit/_config/")||t.startsWith(".testkit/_bundles/")?{classification:"per_run_scratch",reason:"generated Testkit runtime state"}:{classification:"testkit_state",reason:"Testkit-owned state outside a more specific storage class"}}function W(e,t){return{root:e,largestFileLimit:t,totalFiles:0,totalLogicalBytes:0,totalUniqueBytes:0,largestFiles:[],duplicateRepresentations:[]}}function*_(e){const t=A(e).sort((i,s)=>i.name.localeCompare(s.name));for(const i of t){const s=r.join(e,i.name);i.isDirectory()?yield*_(s):i.isFile()&&(yield s)}}function A(e){try{return c.readdirSync(e,{withFileTypes:!0})}catch(t){if(t instanceof Error&&"code"in t&&t.code==="ENOENT")return[];throw t}}function E(e,t){if(I(t))throw T(t);const i=m(t),s=r.resolve(e,i);if(S(e,s,t),c.existsSync(s)){const u=c.realpathSync.native(e),l=c.realpathSync.native(s);S(u,l,t)}return{rootDir:s,rootRelativePath:i}}function S(e,t,i){const s=r.relative(e,t);if(s===".."||s.startsWith(`..${r.sep}`)||r.isAbsolute(s))throw T(i)}function I(e){return r.isAbsolute(e)||r.posix.isAbsolute(e)||r.win32.isAbsolute(e)}function T(e){return new Error(`Storage inventory root must resolve within the product directory: ${e}`)}function m(e){return L(e||"").replace(/\\/g,"/").replace(/^\/+/,"")}const L=String;

package/dist/evidence/storage.d.ts

@@ -0,0 +1,27 @@
+import crypto from "crypto";
+import type { RunArtifactDocument } from "./reporting-types.js";
+import { type RunBundleArtifact, type UnknownRecord } from "./contracts.js";
+export { isObjectRecord } from "./read-fields.js";
+export declare function readJsonFile(filePath: string): unknown;
+export declare function runIncludesFile(artifact: RunBundleArtifact, selector: string): boolean;
+export declare function requireRunId(artifact: RunArtifactDocument): string;
+export declare function normalizeRunId(runId: unknown): string;
+export declare function walkFiles(root: string): string[];
+export declare function treeBytes(root: string): number;
+export declare function writeBufferAtomic(filePath: string, buffer: Buffer): void;
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function hashFile(filePath: string): string;
+export declare function sha256(value: crypto.BinaryLike): string;
+export declare function stableJson(value: unknown): string;
+export declare function objectRecords(value: unknown): UnknownRecord[];
+export declare function resolveRunBundleDirectory(productDir: string, runId: string): string;
+export declare function resolveRunsRoot(productDir: string, create: boolean): string;
+export declare function requirePublicationPathOutsideResults(productDir: string, candidatePath: string): void;
+export declare function resolveManifestEntryPath(bundleDir: string, relativePath: string): string;
+export declare function optionalStringArray(value: unknown): string[];
+export declare function optionalUnknownArray(value: unknown): unknown[];
+export declare function errorMessage(error: unknown): string;
+export declare function bundleRelativePath(runId: string, child: string): string;
+export declare function resultsRoot(productDir: string): string;
+export declare function normalizePath(filePath: string): string;
+export declare function sanitizeSegment(value: string): string;

package/dist/evidence/storage.js

@@ -0,0 +1,2 @@
+import{isPathWithin as y}from"../process/files/paths.js";import S from"crypto";import i from"fs";import o from"path";import{RUNS_DIRNAME as p}from"./contracts.js";import{isObjectRecord as h,requireManifestRelativePath as x}from"./read-fields.js";export{isObjectRecord}from"./read-fields.js";export function readJsonFile(r){try{return JSON.parse(i.readFileSync(r,"utf8"))}catch(t){throw new Error(`Invalid JSON in ${r}: ${errorMessage(t)}`,{cause:t})}}export function runIncludesFile(r,t){const e=normalizePath(t);return r.services.some(n=>n.suites.some(u=>u.files?.some(s=>s.path===e||s.path.endsWith(e))))}export function requireRunId(r){const t=r.run.id==null?null:normalizeRunId(r.run.id);if(t===null)throw new Error("Cannot seal a run bundle without a run id");return t}export function normalizeRunId(r){const t=typeof r=="string"?r:"";if(!t||t==="."||t===".."||t.includes("\0")||t.includes("/")||t.includes("\\"))throw new Error(`Invalid Testkit run id: ${t||"<empty>"}`);return t}export function walkFiles(r){if(!i.existsSync(r))return[];const t=[];for(const e of i.readdirSync(r,{withFileTypes:!0})){const n=o.join(r,e.name);e.isDirectory()?t.push(...walkFiles(n)):e.isFile()&&t.push(n)}return t}export function treeBytes(r){return walkFiles(r).reduce((t,e)=>t+i.statSync(e).size,0)}export function writeBufferAtomic(r,t){i.mkdirSync(o.dirname(r),{recursive:!0});const e=`${r}.${String(process.pid)}.${String(Date.now())}.tmp`;i.writeFileSync(e,t);try{i.renameSync(e,r)}catch(n){if(i.rmSync(e,{force:!0}),!i.existsSync(r))throw n}}export function writeJson(r,t){i.mkdirSync(o.dirname(r),{recursive:!0}),i.writeFileSync(r,`${JSON.stringify(t,null,2)}
+`)}export function hashFile(r){return sha256(i.readFileSync(r))}export function sha256(r){return S.createHash("sha256").update(r).digest("hex")}export function stableJson(r){return JSON.stringify(l(r))}function l(r){return Array.isArray(r)?r.map(l):h(r)?Object.fromEntries(Object.keys(r).sort().map(t=>[t,l(r[t])])):r}export function objectRecords(r){return Array.isArray(r)?r.filter(h):[]}export function resolveRunBundleDirectory(r,t){const e=resolveRunsRoot(r,!1),n=o.join(e,t),u=i.lstatSync(n,{throwIfNoEntry:!1});if(u===void 0)return n;if(u.isSymbolicLink())throw new Error(`Immutable run bundle directory must not be a symbolic link: ${t}`);if(!u.isDirectory())throw new Error(`Immutable run bundle path must be a directory: ${t}`);const s=i.realpathSync(e),c=i.realpathSync(n),a=o.relative(s,c);if(a.length===0||a===".."||a.startsWith(`..${o.sep}`)||o.isAbsolute(a))throw new Error(`Immutable run bundle directory must resolve within the runs root: ${t}`);return n}export function resolveRunsRoot(r,t){const e=o.resolve(r),n=resultsRoot(e),u=o.join(n,p);if(t)b(e,n,"Testkit results root"),i.mkdirSync(n,{recursive:!0});else if(!i.existsSync(n))return u;const s=m(n,"Testkit results root");if(f(i.realpathSync(e),s,"Testkit results root must resolve within the product directory"),t)i.mkdirSync(u,{recursive:!0});else if(!i.existsSync(u))return u;const c=m(u,"Immutable run bundles root");return f(s,c,"Immutable run bundles root must resolve within .testkit/results"),u}function b(r,t,e){const n=o.resolve(r),u=i.realpathSync(n);let s=o.resolve(t),c=i.lstatSync(s,{throwIfNoEntry:!1});for(;c===void 0;){const a=o.dirname(s);if(a===s)throw new Error(`${e} has no existing parent directory`);s=a,c=i.lstatSync(s,{throwIfNoEntry:!1})}if(s!==n&&c.isSymbolicLink())throw new Error(`${e} must not traverse a symbolic link`);if(!c.isDirectory())throw new Error(`${e} parent must be a directory`);f(u,i.realpathSync(s),`${e} must resolve within the product directory`,!0)}function m(r,t){const e=i.lstatSync(r,{throwIfNoEntry:!1});if(e===void 0)throw new Error(`${t} does not exist`);if(e.isSymbolicLink())throw new Error(`${t} must not be a symbolic link`);if(!e.isDirectory())throw new Error(`${t} must be a directory`);return i.realpathSync(r)}function f(r,t,e,n=!1){const u=o.relative(r,t);if(!n&&u.length===0||u===".."||u.startsWith(`..${o.sep}`)||o.isAbsolute(u))throw new Error(e)}export function requirePublicationPathOutsideResults(r,t){const e=o.resolve(resultsRoot(r)),n=o.resolve(t);if(y(e,n))throw new Error("Publication directory must be outside .testkit/results");const u=i.realpathSync(e);let s=n,c=i.lstatSync(s,{throwIfNoEntry:!1});for(;c===void 0;){const d=o.dirname(s);if(d===s)throw new Error("Publication directory has no existing parent");s=d,c=i.lstatSync(s,{throwIfNoEntry:!1})}const a=i.realpathSync(s);if(y(u,a))throw new Error("Publication directory must be outside .testkit/results")}export function resolveManifestEntryPath(r,t){const e=o.resolve(r),n=o.resolve(e,x(t,"manifest entry path"));return w(e,n,t),i.existsSync(n)&&w(i.realpathSync(e),i.realpathSync(n),t),n}function w(r,t,e){const n=o.relative(r,t);if(n.length===0||n===".."||n.startsWith(`..${o.sep}`)||o.isAbsolute(n))throw new Error(`manifest path escapes bundle directory: ${e}`)}export function optionalStringArray(r){return Array.isArray(r)?r.filter(t=>typeof t=="string"):[]}export function optionalUnknownArray(r){return Array.isArray(r)?r:[]}export function errorMessage(r){return r instanceof Error?r.message:String(r)}export function bundleRelativePath(r,t){return normalizePath(o.join(".testkit","results",p,r,t))}export function resultsRoot(r){return o.join(r,".testkit","results")}export function normalizePath(r){return r.split(o.sep).join("/")}export function sanitizeSegment(r){return r.toLowerCase().replace(/[^a-z0-9._-]+/gu,"-").replace(/^-+|-+$/gu,"")||"product"}

package/dist/evidence/timing.d.ts

@@ -0,0 +1,23 @@
+export interface TimingEntry {
+    avgDurationMs: number;
+    durationMs: number;
+    lastDurationMs: number;
+    lastStatus: string | null;
+    maxDurationMs: number;
+    minDurationMs: number;
+    runs: number;
+    updatedAt: string | null;
+}
+export type TimingFileMap = Readonly<Record<string, TimingEntry | undefined>>;
+export interface Timings {
+    files: TimingFileMap;
+    version: 2;
+}
+export interface TimingUpdate {
+    readonly durationMs: number;
+    readonly key: string;
+    readonly status?: string | null;
+}
+export declare function createEmptyTimings(): Timings;
+export declare function normalizeTimings(parsed: unknown): Timings;
+export declare function applyTimingUpdates(timings: Timings, updates: readonly TimingUpdate[], updatedAt?: string): Timings;

package/dist/evidence/timing.js

@@ -0,0 +1 @@
+export function createEmptyTimings(){return{version:2,files:{}}}export function normalizeTimings(t){if(!m(t)||t.version!==2||!m(t.files))return createEmptyTimings();const n={};for(const[e,r]of Object.entries(t.files)){if(!m(r))continue;const u=D(r);u&&(n[e]=u)}return{version:2,files:n}}export function applyTimingUpdates(t,n,e=new Date().toISOString()){const r={...t.files},u=e||null;for(const o of n){const i=Math.max(1,Math.round(o.durationMs)),s=r[o.key];if(!s){r[o.key]={durationMs:i,avgDurationMs:i,lastDurationMs:i,minDurationMs:i,maxDurationMs:i,runs:1,lastStatus:o.status||null,updatedAt:u};continue}const M=s.runs,c=M+1,d=s.avgDurationMs||s.durationMs||i,f=Math.max(1,Math.round((d*M+i)/c));r[o.key]={durationMs:f,avgDurationMs:f,lastDurationMs:i,minDurationMs:Math.min(s.minDurationMs||i,i),maxDurationMs:Math.max(s.maxDurationMs||i,i),runs:c,lastStatus:(o.status||null)??s.lastStatus,updatedAt:u}}return{version:2,files:r}}function D(t){if(!p(t.durationMs))return null;const n=a(t.durationMs);return{durationMs:n,avgDurationMs:a(t.avgDurationMs,n),lastDurationMs:a(t.lastDurationMs,n),minDurationMs:a(t.minDurationMs,n),maxDurationMs:a(t.maxDurationMs,n),runs:g(t.runs),lastStatus:l(t.lastStatus),updatedAt:l(t.updatedAt)}}function p(t){return typeof t=="number"?Number.isFinite(t):typeof t!="string"||t.trim().length===0?!1:Number.isFinite(Number(t))}function a(t,n=0){const r=Number(t||n);return Number.isFinite(r)?Math.max(0,Math.round(r)):n}function g(t){const n=Number(t||0);return Number.isFinite(n)?Math.max(0,Math.floor(n)):0}function l(t){return typeof t=="string"&&t.length>0?t:null}function m(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}

package/dist/file.d.ts

@@ -0,0 +1,11 @@
+import type { EngineId } from "./domain/identifiers.js";
+import type { RuntimeIsolationPolicy } from "./domain/runtime-isolation-contract.js";
+export interface TestkitFileMetadata {
+    engine: EngineId;
+    locks?: string[];
+    runtimeIsolation?: RuntimeIsolationPolicy;
+    skip?: string | {
+        reason: string;
+    };
+}
+export declare function defineFile(metadata: TestkitFileMetadata): TestkitFileMetadata;

package/dist/file.js

@@ -0,0 +1 @@
+export function defineFile(e){return e}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineFile } from "./file.js";
+export type { EngineId } from "./domain/identifiers.js";
+export type { TestkitFileMetadata } from "./file.js";
+export type { RuntimeIsolationPolicy } from "./domain/runtime-isolation-contract.js";

package/dist/index.js

@@ -0,0 +1 @@
+export{defineFile}from"./file.js";

package/dist/kernel/error-serialization.d.ts

@@ -0,0 +1,38 @@
+export type ErrorMetadataPrimitive = string | number | boolean | null;
+export type ErrorMetadataValue = ErrorMetadataPrimitive | ErrorMetadataObject | ErrorMetadataValue[];
+export interface ErrorMetadataObject {
+    [key: string]: ErrorMetadataValue;
+}
+export interface SerializedErrorOperation {
+    id?: string;
+    source: string;
+    name: string;
+    kind: string;
+    summary?: string;
+    scope: ErrorMetadataObject;
+    status?: string;
+    error?: string;
+}
+export interface SerializedError {
+    name: string;
+    message: string;
+    code?: string;
+    exitCode?: number;
+    status?: number;
+    phase?: string;
+    operation?: SerializedErrorOperation;
+    diagnostics?: ErrorMetadataObject;
+    stack?: string;
+}
+export interface SerializeErrorOptions {
+    includeStack?: boolean;
+}
+export declare function attachErrorOperation<ErrorValue>(error: ErrorValue, operation: unknown): ErrorValue;
+export declare function attachErrorDiagnostics<ErrorValue>(error: ErrorValue, diagnostics: unknown): ErrorValue;
+export declare function getErrorOperation(error: unknown): SerializedErrorOperation | null;
+export declare function getErrorDiagnostics(error: unknown): ErrorMetadataObject;
+export declare function errorMessage(error: unknown): string;
+export declare function formatError(error: unknown): string;
+export declare function sanitizeErrorMessage(message: string): string;
+export declare function errorDetail(error: unknown): string;
+export declare function serializeError(error: unknown, { includeStack }?: Readonly<SerializeErrorOptions>): SerializedError;