@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/distribution.d.ts

@@ -0,0 +1,528 @@
+/**
+ * distribution.ts — binary, package, delivery and release-evidence contracts.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (binary, packager, release) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+/**
+ * binary builder plans portable artifacts without choosing a compiler vendor.
+ */
+export declare const binarytargets: readonly string[];
+/** Creates a deterministic binary build plan from explicit options. */
+export declare function portablebinaryplan(options?: {}): {
+    name: any;
+    target: any;
+    entry: any;
+    output: any;
+    command: any;
+    minify: any;
+    embedruntime: any;
+    externaldependencies: any;
+    metadata: any;
+};
+/** Returns an artifact manifest without writing files or running a compiler. */
+export declare function binarymanifest(plan: any): {
+    name: any;
+    target: any;
+    entry: any;
+    output: any;
+    files: any[];
+    reproducible: boolean;
+    metadata: any;
+};
+/** Resolves an injected builder and preserves the plan as the execution boundary. */
+export declare function buildbinary(plan: any, builder: any): Promise<any>;
+/**
+ * archive inspection validates declared entry metadata before any caller-owned extraction adapter runs.
+ */
+/** Validates portable archive limits without opening an archive. */
+export declare function archivelimits(input?: {}): Readonly<{
+    maxentries: number;
+    maxdepth: number;
+    maxoutputbytes: number;
+    maxratio: number;
+}>;
+/** Inspects declared archive entries and returns explicit acceptance or denial evidence. */
+export declare function archiveinspection(input?: {}): Readonly<{
+    version: 1;
+    state: "accepted" | "denied";
+    limits: Readonly<{
+        maxentries: number;
+        maxdepth: number;
+        maxoutputbytes: number;
+        maxratio: number;
+    }>;
+    entries: any;
+    outputbytes: number;
+    reasons: readonly any[];
+}>;
+/** Requires a caller-owned extraction adapter and denies an unsafe inspection result. */
+export declare function extractarchive(inspection: any, adapter: any): Promise<any>;
+/**
+ * binary transformation contracts classify inputs and delegate execution to isolated caller-owned adapters.
+ */
+/** Classifies a small binary prefix without trusting a filename extension. */
+export declare function magicbytes(input: any): Readonly<{
+    format: "wasm";
+    executable: true;
+}> | Readonly<{
+    format: "elf";
+    executable: true;
+}> | Readonly<{
+    format: "pe";
+    executable: true;
+}> | Readonly<{
+    format: "zip";
+    executable: false;
+}> | Readonly<{
+    format: "unknown";
+    executable: false;
+}>;
+/** Validates a bounded WASM transformation plan without compiling or instantiating a module. */
+export declare function wasmplan(input?: {}): Readonly<{
+    version: 1;
+    source: string;
+    imports: readonly unknown[];
+    budget: Readonly<{
+        maxbytes: number;
+        maxoutputbytes: number;
+        maxmilliseconds: number;
+        network: boolean;
+    }>;
+    target: string;
+    policyversion: number;
+    state: "caller-executes";
+}>;
+/** Builds a reproducible transformation cache key from verified inputs and normalized policy. */
+export declare function transformationkey(input?: {}): string;
+/** Validates an immutable cache manifest that can be reused only by matching policy and toolchain identities. */
+export declare function transformationcache(input?: {}): Readonly<{
+    version: 1;
+    key: string;
+    source: string;
+    compiler: string;
+    policyversion: number;
+    outputs: any;
+    verified: boolean;
+}>;
+/** Explains whether a verified cache manifest can serve a requested transformation. */
+export declare function cachedecision(manifest: any, request: any): Readonly<{
+    reusable: boolean;
+    reasons: readonly any[];
+    manifest: Readonly<{
+        version: 1;
+        key: string;
+        source: string;
+        compiler: string;
+        policyversion: number;
+        outputs: any;
+        verified: boolean;
+    }>;
+}>;
+/** Rejects cache reuse for outputs that are sensitive, environment-bound, partial, or unverified. */
+export declare function cacheeligibility(input?: {}): Readonly<{
+    eligible: boolean;
+    reasons: readonly any[];
+}>;
+/** Runs a transformation only through an injected isolated adapter and verifies declared output digests. */
+export declare function executeisolated(plan: any, adapter: any): Promise<Readonly<{
+    version: 1;
+    state: "completed";
+    outputs: any;
+}>>;
+/**
+ * packager manifest context describes publication and platform artifacts without
+ * executing a platform command or selecting a vendor toolchain.
+ */
+export declare const artifactformats: Readonly<{
+    desktop: readonly string[];
+    mobile: readonly string[];
+    browser: readonly string[];
+    web: readonly string[];
+    package: readonly string[];
+}>;
+/** Creates the public dotted artifact stem for a target and version. */
+export declare function artifactname(target: any, version: any, format: any): string;
+/** Creates the supported cross-platform release matrix for a version. */
+export declare function releaseartifactmatrix(version: any, options?: {}): {
+    version: string;
+    signing: string;
+    entries: {
+        surface: any;
+        platform: any;
+        architecture: any;
+        formats: any;
+        files: any;
+        signing: any;
+        checksums: string;
+        manifest: string;
+    }[];
+};
+/** Creates a distribution manifest for caller-owned build and publication steps. */
+export declare function distributionmanifest(options?: {}): {
+    name: any;
+    version: any;
+    entry: any;
+    modes: any;
+    targets: any;
+    files: any;
+    metadata: any;
+};
+/** Creates a caller-owned artifact plan without invoking a platform toolchain. */
+export declare function targetplan(manifest: any, target: any, options?: {}): {
+    name: any;
+    version: any;
+    target: any;
+    format: any;
+    entry: any;
+    output: any;
+    command: any;
+    generated: boolean;
+    credentials: string;
+    metadata: any;
+};
+/** Creates a declarative Node SEA or caller-selected binary build plan. */
+export declare function binaryplan(manifest: any, options?: {}): {
+    tool: any;
+    command: any;
+    entry: any;
+    targets: any;
+};
+/** Creates an OCI container plan with caller-controlled base, workdir and command. */
+export declare function containerplan(manifest: any, options?: {}): {
+    base: any;
+    workdir: any;
+    command: any;
+    dockerfile: string;
+};
+/**
+ * publish plans describe registry targets without executing a publish or requiring credentials.
+ */
+export declare function publishplan(manifest: any, options?: {}): {
+    package: {
+        registry: any;
+        name: any;
+        version: any;
+        command: string;
+    };
+    github: {
+        repository: any;
+        packages: boolean;
+        command: string;
+    };
+    container: {
+        registry: any;
+        image: any;
+        version: any;
+        command: string;
+    };
+    maven: {
+        registry: any;
+        name: any;
+        version: any;
+        command: string;
+    };
+    nuget: {
+        registry: any;
+        name: any;
+        version: any;
+        command: string;
+    };
+    rubygems: {
+        registry: any;
+        name: any;
+        version: any;
+        command: string;
+    };
+    cdn: {
+        name: string;
+        url: string;
+    }[];
+};
+export declare function registrymanifest(manifest: any, options?: {}): {
+    name: any;
+    version: any;
+    surfaces: any[];
+    registries: string[];
+};
+/**
+ * delivery manifests verify immutable chunks and keep PWA registration caller-owned.
+ */
+/** Creates an ordered immutable delivery manifest from verified chunk metadata. */
+export declare function deliverymanifest(input?: {}): Readonly<{
+    version: 1;
+    id: string;
+    chunks: any;
+    totalbytes: any;
+    visibility: "private" | "public";
+}>;
+/** Verifies supplied chunk bytes against a manifest without executing, importing, or caching them. */
+export declare function verifydelivery(manifest: any, supplied?: any[]): Readonly<{
+    version: 1;
+    valid: any;
+    results: any;
+}>;
+/** Produces a host PWA plan that never registers a service worker or mutates browser state. */
+export declare function pwaplan(input?: {}): Readonly<{
+    version: 1;
+    scope: string;
+    offline: boolean;
+    state: "caller-registers" | "unsupported";
+    update: "manual" | "prompt";
+    cache: "caller-configures" | "disabled";
+}>;
+/** Validates a caller-reported CDN capability set without contacting a CDN provider. */
+export declare function cdncapabilities(input?: {}): Readonly<{
+    version: 1;
+    immutable: boolean;
+    purge: boolean;
+    range: boolean;
+    integrityheaders: boolean;
+    cors: boolean;
+    visibility: "private" | "public";
+    state: "caller-reports";
+}>;
+/**
+ * target manifest CLI writes declarative target plans for CI artifact jobs.
+ * It never invokes a desktop, mobile, store or signing toolchain.
+ */
+/** Reads the distribution manifest and writes one target plan. */
+export declare function writeTargetPlan(target: string, format?: string, output?: string): Promise<string>;
+/** Builds deterministic release metadata files for caller-selected artifacts. */
+export declare function createassets(options?: {}): Promise<{
+    output: string;
+    files: {
+        checksums: string;
+        manifest: string;
+        sbom: string;
+        provenance: string;
+    };
+    subjects: {
+        name: string;
+        digest: string;
+        bytes: never;
+        updatedat: number;
+    }[];
+    sbom: {
+        bomFormat: string;
+        specVersion: string;
+        serialNumber: string;
+        version: number;
+        metadata: {
+            component: {
+                type: string;
+                name: string;
+                version: string;
+            };
+        };
+        components: {
+            "bom-ref": string;
+            name: string;
+            version: string;
+            purl: string;
+            scope: string;
+            type: string;
+        }[];
+    };
+    provenance: {
+        _type: string;
+        subject: {
+            name: string;
+            digest: {
+                sha256: string;
+            };
+        }[];
+        predicateType: string;
+        predicate: {
+            buildDefinition: {
+                buildType: string;
+                externalParameters: {
+                    package: string;
+                    version: string;
+                };
+                internalParameters: {};
+            };
+            runDetails: {
+                builder: {
+                    id: string;
+                };
+                metadata: {
+                    invocationId: string;
+                };
+            };
+        };
+    };
+    retention: {
+        policy: {};
+        evaluatedat: number;
+        decisions: {
+            name: string;
+            bytes: number;
+            updatedat: number;
+            action: string;
+            reasons: any[];
+        }[];
+    };
+}>;
+/** Computes deterministic keep or prune decisions without deleting caller files. */
+export declare function retentionplan(artifacts?: any[], options?: {}): {
+    policy: {};
+    evaluatedat: number;
+    decisions: {
+        name: string;
+        bytes: number;
+        updatedat: number;
+        action: string;
+        reasons: any[];
+    }[];
+};
+/** Creates a compact CycloneDX component list from the root lockfile dependencies. */
+export declare function createsbom(packagejson: any, lockjson?: {}): {
+    bomFormat: string;
+    specVersion: string;
+    serialNumber: string;
+    version: number;
+    metadata: {
+        component: {
+            type: string;
+            name: string;
+            version: string;
+        };
+    };
+    components: {
+        "bom-ref": string;
+        name: string;
+        version: string;
+        purl: string;
+        scope: string;
+        type: string;
+    }[];
+};
+/** Creates an in-toto statement whose subjects are the caller-selected release artifacts. */
+export declare function createprovenance(packagejson: any, subjects?: any[], options?: {}): {
+    _type: string;
+    subject: {
+        name: string;
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: string;
+    predicate: {
+        buildDefinition: {
+            buildType: string;
+            externalParameters: {
+                package: string;
+                version: string;
+            };
+            internalParameters: {};
+        };
+        runDetails: {
+            builder: {
+                id: string;
+            };
+            metadata: {
+                invocationId: string;
+            };
+        };
+    };
+};
+/** Verifies a release checksum file and its correlated public manifest. */
+export declare function verifyassets(options?: {}): Promise<{
+    valid: boolean;
+    version: string;
+    signing: string;
+    files: any[];
+}>;
+/** Normalizes an immutable, caller-supplied artifact evidence record. */
+export declare function releaseevidence(input?: Record<string, unknown>): {
+    version: number;
+    kind: string;
+    status: string;
+    subjectdigest: string;
+    producer: string;
+    workflow: string;
+    verificationmethod: string;
+    verifiedat: number;
+    metadata: {
+        [x: string]: unknown;
+    };
+};
+/** Evaluates evidence against a caller-owned policy and returns reason codes, never a trust claim. */
+export declare function evaluateevidence(input?: Record<string, unknown>): {
+    version: number;
+    decision: string;
+    reasons: string[];
+    subjectdigest: string;
+    requiredkinds: string[];
+    evidence: {
+        version: number;
+        kind: string;
+        status: string;
+        subjectdigest: string;
+        producer: string;
+        workflow: string;
+        verificationmethod: string;
+        verifiedat: number;
+        metadata: {
+            [x: string]: unknown;
+        };
+    }[];
+};
+/** Builds a data-only readiness receipt for a release that a caller may later execute. */
+export declare function releasereadiness(input?: Record<string, unknown>): {
+    version: number;
+    sourcetag: string;
+    manifestversions: Record<string, string>;
+    requiredgates: Record<string, string>;
+    artifactplandigest: string;
+    targets: string[];
+    signingstatus: string;
+    evaluation: {
+        version: number;
+        decision: string;
+        reasons: string[];
+        subjectdigest: string;
+        requiredkinds: string[];
+        evidence: {
+            version: number;
+            kind: string;
+            status: string;
+            subjectdigest: string;
+            producer: string;
+            workflow: string;
+            verificationmethod: string;
+            verifiedat: number;
+            metadata: {
+                [x: string]: unknown;
+            };
+        }[];
+    };
+    decision: string;
+    ready: boolean;
+    reasons: string[];
+};
+/** Maps an already-completed local checksum verification result to evidence records. */
+export declare function evidencefromverification(input?: Record<string, unknown>): {
+    version: number;
+    releaseversion: string;
+    signingstatus: string;
+    evidence: {
+        version: number;
+        kind: string;
+        status: string;
+        subjectdigest: string;
+        producer: string;
+        workflow: string;
+        verificationmethod: string;
+        verifiedat: number;
+        metadata: {
+            [x: string]: unknown;
+        };
+    }[];
+};