Include vendored traverse-embedder-web dist for CI installs

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: enricopiovesan

.gitignore

@@ -1,6 +1,8 @@
 # Dependencies
 node_modules/
 dist/
+!vendor/**/dist/
+!vendor/**/dist/**
 
 # Test coverage
 coverage/

vendor/traverse-embedder-web/dist/bundleEmbedder.d.ts

@@ -0,0 +1,35 @@
+import type { BundleLoader } from "./bundleLoader.js";
+import type { CompatibleLifecycleOutcome, CompatibleStartOutcome, EventCallback, JsonValue, ShutdownOutcome, SubmitOutcome, TraverseEmbedderApi } from "./types.js";
+/** Configuration for `BundleEmbedder.init` (`runtime.init` input). */
+export interface BundleEmbedderConfig {
+    /** Path or URL to the application bundle's `app.manifest.json`. */
+    readonly manifestPath: string;
+    /** Loader used to fetch bundle files (browser: `FetchBundleLoader`). */
+    readonly loader: BundleLoader;
+    /** Workspace identity recorded on events. Defaults to `local-default`. */
+    readonly workspaceId?: string;
+    /** Platform identity checked against compatible-capability allowlists. */
+    readonly platform?: string;
+}
+export declare class BundleEmbedder implements TraverseEmbedderApi {
+    private readonly core;
+    private readonly wasmTargets;
+    private readonly workflowTargets;
+    private readonly wasmComponentEvidence;
+    private constructor();
+    /**
+     * `runtime.init`: load, digest-verify, host-ABI-validate, and compile the
+     * application bundle. Rejects deterministically with a `BundleRejectedError`
+     * and never falls back to a sidecar (spec 068 NFR-001).
+     */
+    static init(config: BundleEmbedderConfig): Promise<BundleEmbedder>;
+    submit(targetId: string, input: JsonValue): SubmitOutcome;
+    private submitCapability;
+    private submitWorkflow;
+    subscribe(callback: EventCallback): void;
+    startCompatible(capabilityId: string, input: JsonValue): CompatibleStartOutcome;
+    stopCompatible(capabilityId: string, instanceId?: string | null): CompatibleLifecycleOutcome;
+    killCompatible(capabilityId: string, instanceId?: string | null): CompatibleLifecycleOutcome;
+    shutdown(): ShutdownOutcome;
+    releaseEvidence(): JsonValue;
+}

vendor/traverse-embedder-web/dist/bundleEmbedder.js

@@ -0,0 +1,36 @@
+/**
+ * Loads application bundle files (manifests, contracts, WASM artifacts) by
+ * relative path. `BundleEmbedder` depends only on this interface, so a
+ * browser host supplies `FetchBundleLoader` (production) and a Node host
+ * (tests, Electron main-process embedding) supplies `NodeFsBundleLoader` —
+ * neither is baked into the public API surface (spec 068: no `traverse-cli
+ * serve` dependency in the production path).
+ */
+export interface BundleLoader {
+    /** Resolves `relativePath` against the directory containing `basePath`. */
+    resolve(basePath: string, relativePath: string): string;
+    /** Loads a UTF-8 text file (manifests, contracts, workflow definitions). */
+    loadText(path: string): Promise<string>;
+    /** Loads raw bytes (WASM artifacts). */
+    loadBytes(path: string): Promise<Uint8Array>;
+}
+/**
+ * Browser bundle loader: resolves paths as URLs relative to the manifest
+ * URL and loads them via `fetch`. This is the production loader — no
+ * `traverse-cli serve` sidecar is involved.
+ */
+export declare class FetchBundleLoader implements BundleLoader {
+    resolve(basePath: string, relativePath: string): string;
+    loadText(path: string): Promise<string>;
+    loadBytes(path: string): Promise<Uint8Array>;
+}
+/**
+ * Node.js filesystem bundle loader, for tests and non-browser hosts
+ * (Electron main process, server-side prerendering). Uses dynamic `import`
+ * so `node:fs` is never a static dependency of the browser entry point.
+ */
+export declare class NodeFsBundleLoader implements BundleLoader {
+    resolve(basePath: string, relativePath: string): string;
+    loadText(path: string): Promise<string>;
+    loadBytes(path: string): Promise<Uint8Array>;
+}

vendor/traverse-embedder-web/dist/bundleLoader.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Loads application bundle files (manifests, contracts, WASM artifacts) by
+ * relative path. `BundleEmbedder` depends only on this interface, so a
+ * browser host supplies `FetchBundleLoader` (production) and a Node host
+ * (tests, Electron main-process embedding) supplies `NodeFsBundleLoader` —
+ * neither is baked into the public API surface (spec 068: no `traverse-cli
+ * serve` dependency in the production path).
+ */
+function dirname(path) {
+    const index = path.lastIndexOf("/");
+    return index === -1 ? "" : path.slice(0, index);
+}
+function joinPosix(base, relative) {
+    if (relative.startsWith("/") || /^[a-zA-Z]+:/.test(relative)) {
+        return relative;
+    }
+    const segments = `${base}/${relative}`.split("/");
+    const resolved = [];
+    for (const segment of segments) {
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(segment);
+    }
+    return (base.startsWith("/") ? "/" : "") + resolved.join("/");
+}
+/**
+ * Browser bundle loader: resolves paths as URLs relative to the manifest
+ * URL and loads them via `fetch`. This is the production loader — no
+ * `traverse-cli serve` sidecar is involved.
+ */
+export class FetchBundleLoader {
+    resolve(basePath, relativePath) {
+        const documentBase = typeof document !== "undefined" ? document.baseURI : globalThis.location.href;
+        return new URL(relativePath, new URL(basePath, documentBase)).toString();
+    }
+    async loadText(path) {
+        const response = await fetch(path);
+        if (!response.ok) {
+            throw new Error(`failed to fetch '${path}': HTTP ${response.status}`);
+        }
+        return response.text();
+    }
+    async loadBytes(path) {
+        const response = await fetch(path);
+        if (!response.ok) {
+            throw new Error(`failed to fetch '${path}': HTTP ${response.status}`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+}
+/**
+ * Node.js filesystem bundle loader, for tests and non-browser hosts
+ * (Electron main process, server-side prerendering). Uses dynamic `import`
+ * so `node:fs` is never a static dependency of the browser entry point.
+ */
+export class NodeFsBundleLoader {
+    resolve(basePath, relativePath) {
+        return joinPosix(dirname(basePath), relativePath);
+    }
+    async loadText(path) {
+        const { readFile } = await import("node:fs/promises");
+        return readFile(path, "utf8");
+    }
+    async loadBytes(path) {
+        const { readFile } = await import("node:fs/promises");
+        const buffer = await readFile(path);
+        return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    }
+}

vendor/traverse-embedder-web/dist/bundleLoader.js

@@ -0,0 +1,54 @@
+import type { EmbedderError, JsonValue } from "./types.js";
+/** Thrown when a bundle is rejected at the embedder boundary. */
+export declare class BundleRejectedError extends Error {
+    readonly embedderError: EmbedderError;
+    constructor(error: EmbedderError);
+}
+/** One bundled component reference parsed from the app manifest. */
+export interface BundleComponentSummary {
+    readonly componentId: string;
+    readonly version: string;
+    readonly digest: string;
+    readonly manifestPath: string;
+}
+/** One bundled workflow reference parsed from the app manifest. */
+export interface BundleWorkflowSummary {
+    readonly workflowId: string;
+    readonly workflowVersion: string;
+    readonly path: string;
+}
+/** Deterministic bundle compatibility summary (spec 068 NFR-001). */
+export interface BundleCompatibility {
+    readonly appId: string;
+    readonly appVersion: string;
+    readonly schemaVersion: string;
+    readonly components: readonly BundleComponentSummary[];
+    readonly workflowIds: readonly string[];
+    readonly workflows: readonly BundleWorkflowSummary[];
+}
+export declare function asRecord(value: JsonValue | undefined): {
+    [key: string]: JsonValue;
+} | null;
+export declare function requiredString(record: {
+    [key: string]: JsonValue;
+}, key: string, context: string): string;
+export declare function optionalString(record: {
+    [key: string]: JsonValue;
+}, key: string): string | null;
+export declare const SHA256_DIGEST_PATTERN: RegExp;
+/**
+ * Parses and deterministically validates an application bundle manifest
+ * (spec `044-application-bundle-manifest`) for embedder compatibility:
+ * schema version support, component identity, and sha-256 digest metadata.
+ * Rejection never falls back to a sidecar (spec 068 NFR-001).
+ *
+ * @throws {BundleRejectedError} with a stable `EmbedderErrorCode`.
+ */
+export declare function validateBundleCompatibility(appManifest: string | JsonValue): BundleCompatibility;
+/**
+ * Verifies bundled artifact bytes against declared sha-256 digest metadata
+ * using WebCrypto (browser) or the Node.js webcrypto implementation.
+ *
+ * @throws {BundleRejectedError} with `bundle_load_failed` on mismatch.
+ */
+export declare function verifyArtifactDigest(bytes: Uint8Array, declaredDigest: string, artifactLabel: string): Promise<void>;

vendor/traverse-embedder-web/dist/bundleValidation.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Deterministic application bundle manifest validation (spec
+ * `044-application-bundle-manifest`) and artifact digest verification.
+ * Rejection never falls back to a sidecar (spec 068 NFR-001).
+ */
+import { SUPPORTED_BUNDLE_SCHEMA_VERSIONS, embedderError } from "./types.js";
+/** Thrown when a bundle is rejected at the embedder boundary. */
+export class BundleRejectedError extends Error {
+    embedderError;
+    constructor(error) {
+        super(`${error.code}: ${error.message}`);
+        this.name = "BundleRejectedError";
+        this.embedderError = error;
+    }
+}
+export function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function requiredString(record, key, context) {
+    const value = record[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new BundleRejectedError(embedderError("bundle_load_failed", `${context} requires a non-empty string '${key}'`));
+    }
+    return value;
+}
+export function optionalString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : null;
+}
+export const SHA256_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+ * Parses and deterministically validates an application bundle manifest
+ * (spec `044-application-bundle-manifest`) for embedder compatibility:
+ * schema version support, component identity, and sha-256 digest metadata.
+ * Rejection never falls back to a sidecar (spec 068 NFR-001).
+ *
+ * @throws {BundleRejectedError} with a stable `EmbedderErrorCode`.
+ */
+export function validateBundleCompatibility(appManifest) {
+    let parsed;
+    if (typeof appManifest === "string") {
+        try {
+            parsed = JSON.parse(appManifest);
+        }
+        catch (error) {
+            throw new BundleRejectedError(embedderError("bundle_load_failed", `application bundle manifest is not valid JSON: ${String(error)}`));
+        }
+    }
+    else {
+        parsed = appManifest;
+    }
+    const manifest = asRecord(parsed);
+    if (manifest === null) {
+        throw new BundleRejectedError(embedderError("bundle_load_failed", "application bundle manifest must be a JSON object"));
+    }
+    const appId = requiredString(manifest, "app_id", "application bundle manifest");
+    const appVersion = requiredString(manifest, "version", "application bundle manifest");
+    const schemaVersion = requiredString(manifest, "schema_version", "application bundle manifest");
+    if (!SUPPORTED_BUNDLE_SCHEMA_VERSIONS.includes(schemaVersion)) {
+        throw new BundleRejectedError(embedderError("unsupported_bundle_schema", `bundle declares schema_version '${schemaVersion}' but this package supports ` +
+            `[${SUPPORTED_BUNDLE_SCHEMA_VERSIONS.join(", ")}]; no sidecar fallback is attempted`));
+    }
+    const componentsValue = manifest["components"];
+    if (!Array.isArray(componentsValue)) {
+        throw new BundleRejectedError(embedderError("bundle_load_failed", "application bundle manifest requires a 'components' array"));
+    }
+    const components = componentsValue.map((entry, index) => {
+        const component = asRecord(entry);
+        if (component === null) {
+            throw new BundleRejectedError(embedderError("bundle_load_failed", `components[${index}] must be a JSON object`));
+        }
+        const context = `components[${index}]`;
+        const digest = requiredString(component, "digest", context);
+        if (!SHA256_DIGEST_PATTERN.test(digest)) {
+            throw new BundleRejectedError(embedderError("bundle_load_failed", `${context} declares invalid digest metadata '${digest}'; ` +
+                "expected sha256:<64 hex characters>"));
+        }
+        return {
+            componentId: requiredString(component, "component_id", context),
+            version: requiredString(component, "version", context),
+            digest,
+            manifestPath: requiredString(component, "manifest_path", context),
+        };
+    });
+    const workflowsValue = manifest["workflows"];
+    const workflowIds = [];
+    const workflows = [];
+    if (Array.isArray(workflowsValue)) {
+        for (const [index, entry] of workflowsValue.entries()) {
+            const workflow = asRecord(entry);
+            if (workflow === null) {
+                throw new BundleRejectedError(embedderError("bundle_load_failed", `workflows[${index}] must be a JSON object`));
+            }
+            const context = `workflows[${index}]`;
+            const workflowId = requiredString(workflow, "workflow_id", context);
+            workflowIds.push(workflowId);
+            workflows.push({
+                workflowId,
+                workflowVersion: requiredString(workflow, "workflow_version", context),
+                path: requiredString(workflow, "path", context),
+            });
+        }
+    }
+    return { appId, appVersion, schemaVersion, components, workflowIds, workflows };
+}
+/**
+ * Verifies bundled artifact bytes against declared sha-256 digest metadata
+ * using WebCrypto (browser) or the Node.js webcrypto implementation.
+ *
+ * @throws {BundleRejectedError} with `bundle_load_failed` on mismatch.
+ */
+export async function verifyArtifactDigest(bytes, declaredDigest, artifactLabel) {
+    if (!SHA256_DIGEST_PATTERN.test(declaredDigest)) {
+        throw new BundleRejectedError(embedderError("bundle_load_failed", `${artifactLabel} declares invalid digest metadata '${declaredDigest}'`));
+    }
+    const digestBytes = await crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+    const actual = [...new Uint8Array(digestBytes)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    const expected = declaredDigest.slice("sha256:".length);
+    if (actual !== expected) {
+        throw new BundleRejectedError(embedderError("bundle_load_failed", `${artifactLabel} digest mismatch: manifest declares sha256:${expected} ` +
+            `but the bundled artifact hashes to sha256:${actual}; ` +
+            "no sidecar fallback is attempted"));
+    }
+}

vendor/traverse-embedder-web/dist/bundleValidation.js

@@ -0,0 +1,33 @@
+import type { CompatibleLifecycleOutcome, CompatibleStartOutcome, EmbedderError, EmbedderEvent, EventCallback, JsonValue, SubmitOutcome } from "./types.js";
+export declare class EmbedderCore {
+    readonly workspaceId: string;
+    readonly appId: string;
+    readonly appVersion: string;
+    readonly platform: string;
+    readonly compatibleTargets: Map<string, readonly string[]>;
+    private readonly instances;
+    private readonly subscribers;
+    private readonly history;
+    private nextEvent;
+    private nextSession;
+    private nextRequest;
+    private nextInstance;
+    stopped: boolean;
+    constructor(workspaceId: string, appId: string, appVersion: string, platform: string, compatibleTargets: Map<string, readonly string[]>);
+    nextSessionId(): string;
+    nextRequestId(): string;
+    private nextInstanceId;
+    emit(eventType: EmbedderEvent["event_type"], sessionId: string | null, data: JsonValue): void;
+    subscribe(callback: EventCallback): void;
+    emitErrorEvent(sessionId: string | null, error: EmbedderError, data: {
+        [key: string]: JsonValue;
+    }): void;
+    rejectedSubmit(targetId: string, error: EmbedderError): SubmitOutcome;
+    startCompatible(capabilityId: string, input: JsonValue): CompatibleStartOutcome;
+    transitionCompatible(capabilityId: string, instanceId: string | null, targetState: "stopped" | "killed"): CompatibleLifecycleOutcome;
+    private setInstanceState;
+    shutdown(): {
+        killedInstances: number;
+    };
+    evidence(runtimeImplementation: string, wasmComponents: JsonValue): JsonValue;
+}