@mcoda/shared 0.1.75 → 0.1.78

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 ## Unreleased
 - Initial public packaging for @mcoda/shared.
 
+## 0.1.78
+- Add versioned mswarm generic job, lifecycle, capability, and artifact
+  sandbox contracts for owner-local GPU/package jobs.
+
 ## 0.1.9
 - Release v0.1.9.
 

package/README.md

@@ -10,6 +10,7 @@ Shared utilities and schemas used across the mcoda workspace.
 - PathHelper for resolving mcoda directories.
 - CryptoHelper for local secret encryption.
 - CommandMetadata helpers and OpenAPI types.
+- Versioned mswarm generic job, lifecycle, capability, and artifact sandbox contracts.
 - QA profile types.
 
 ## Example

package/dist/index.d.ts

@@ -7,6 +7,10 @@ export * from "./qa/QaReadiness.js";
 export * from "./qa/QaTechStack.js";
 export * from "./metadata/CommandMetadata.js";
 export * from "./llm/LocalRunnerConfig.js";
+export * from "./mswarm/GenericJobContract.js";
+export * from "./mswarm/CapabilityContract.js";
+export * from "./mswarm/ArtifactSandboxContract.js";
+export * from "./mswarm/LifecycleContract.js";
 export * from "./status/TaskStatus.js";
 export type { BacklogLaneTotals, BacklogTotals, BacklogSummary, EffectiveVelocity, EstimateResult, EstimateDurations, EstimateEtas, EstimateStatusCounts, EstimateCompletionMetric, EstimateCompletion, VelocitySource, AgentHealth, AgentHealthStatus, AgentUsageLimitScope, AgentUsageLimitWindowType, AgentUsageLimitStatus, AgentUsageLimitRecord, UpsertAgentUsageLimitInput, RoutingDefaults, RoutingDefault, RoutingProvenance, RoutingCandidate, RoutingPreview, RoutingDefaultsUpdate, RefineTasksRequest, RefineTasksPlan, RefineTasksResult, RefineStrategy, RefineOperation, UpdateTaskOp, SplitTaskOp, MergeTasksOp, UpdateEstimateOp, UpdateInfo, UpdateChannel, ApplyUpdateResponse, } from "./openapi/OpenApiTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -7,4 +7,8 @@ export * from "./qa/QaReadiness.js";
 export * from "./qa/QaTechStack.js";
 export * from "./metadata/CommandMetadata.js";
 export * from "./llm/LocalRunnerConfig.js";
+export * from "./mswarm/GenericJobContract.js";
+export * from "./mswarm/CapabilityContract.js";
+export * from "./mswarm/ArtifactSandboxContract.js";
+export * from "./mswarm/LifecycleContract.js";
 export * from "./status/TaskStatus.js";

package/dist/mswarm/ArtifactSandboxContract.d.ts

@@ -0,0 +1,98 @@
+import type { MswarmArtifactRef, MswarmArtifactScope, MswarmJobLimits, MswarmJobNetworkPolicy, MswarmJobPolicy, MswarmJobTrustMode, MswarmOutputSpec } from "./GenericJobContract.js";
+export declare const MSWARM_ARTIFACT_SANDBOX_SCHEMA_VERSION: "2026-06-14";
+export type MswarmArtifactStorageBackend = "local-dev" | "gateway" | "object-storage";
+export type MswarmArtifactVisibility = "owner-local" | "tenant-scoped";
+export type MswarmSandboxProfileName = "owner-local-process" | "container-cpu" | "container-nvidia";
+export type MswarmArchiveEntryType = "file" | "directory" | "symlink" | "hardlink" | "device" | "other";
+export interface MswarmArtifactAccessPolicy {
+    visibility: MswarmArtifactVisibility;
+    read_by: Array<"runner" | "owner" | "tenant" | "gateway">;
+    write_by: Array<"runner" | "owner" | "gateway">;
+    expires_at?: string;
+}
+export interface MswarmArtifactRetentionPolicy {
+    retain_for_seconds: number;
+    delete_after?: string;
+}
+export interface MswarmArtifactStoreDescriptor {
+    backend: MswarmArtifactStorageBackend;
+    root_uri?: string;
+    bucket?: string;
+    gateway_base_url?: string;
+}
+export interface MswarmArtifactRegistrationRequest {
+    job_id: string;
+    name: string;
+    artifact: MswarmArtifactRef;
+    access?: MswarmArtifactAccessPolicy;
+    retention?: MswarmArtifactRetentionPolicy;
+}
+export interface MswarmRegisteredArtifact extends MswarmArtifactRef {
+    id: string;
+    job_id: string;
+    name: string;
+    scope: MswarmArtifactScope;
+    registered_at: string;
+    store: MswarmArtifactStoreDescriptor;
+    access: MswarmArtifactAccessPolicy;
+    retention: MswarmArtifactRetentionPolicy;
+    local_path?: string;
+}
+export interface MswarmOutputCollectionSpec extends MswarmOutputSpec {
+    max_bytes?: number;
+}
+export interface MswarmArchiveEntryCheck {
+    path: string;
+    type?: MswarmArchiveEntryType;
+    size_bytes?: number;
+}
+export interface MswarmPathValidationResult {
+    ok: boolean;
+    normalized?: string;
+    reason?: string;
+}
+export interface MswarmSandboxProfile {
+    schema_version: typeof MSWARM_ARTIFACT_SANDBOX_SCHEMA_VERSION;
+    name: MswarmSandboxProfileName;
+    trust_mode: MswarmJobTrustMode;
+    network: MswarmJobNetworkPolicy;
+    allow_raw_command: false;
+    filesystem: {
+        working_directory: "per-job";
+        inputs: "read-only";
+        outputs: "write-only";
+        allow_host_paths: false;
+        validate_output_paths: true;
+        validate_archive_entries: true;
+    };
+    container: {
+        enabled: boolean;
+        rootless: boolean;
+        user: string;
+        privileged: false;
+        read_only_root_fs: boolean;
+        gpu: "none" | "nvidia";
+        allowed_images?: string[];
+    };
+    limits: {
+        timeout_sec?: number;
+        max_stdout_bytes?: number;
+        max_stderr_bytes?: number;
+        max_output_bytes?: number;
+        max_artifact_bytes?: number;
+    };
+}
+export declare function normalizeMswarmSafeRelativePath(path: unknown): MswarmPathValidationResult;
+export declare function assertMswarmSafeRelativePath(path: unknown, label?: string): string;
+export declare function validateMswarmOutputSpecPath(output: MswarmOutputSpec): MswarmPathValidationResult;
+export declare function validateMswarmArchiveEntry(entry: MswarmArchiveEntryCheck): MswarmPathValidationResult;
+export declare function defaultMswarmArtifactAccessPolicy(visibility?: MswarmArtifactVisibility): MswarmArtifactAccessPolicy;
+export declare function defaultMswarmArtifactRetentionPolicy(retainForSeconds?: number): MswarmArtifactRetentionPolicy;
+export declare function buildMswarmLocalArtifactUri(jobId: string, relativePath: string): string;
+export declare function buildMswarmSandboxProfile(input: {
+    policy: MswarmJobPolicy;
+    limits?: MswarmJobLimits;
+    containerized?: boolean;
+    gpu?: "none" | "nvidia";
+}): MswarmSandboxProfile;
+//# sourceMappingURL=ArtifactSandboxContract.d.ts.map

package/dist/mswarm/ArtifactSandboxContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactSandboxContract.d.ts","sourceRoot":"","sources":["../../src/mswarm/ArtifactSandboxContract.ts"],"names":[],"mappings":"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"}

package/dist/mswarm/ArtifactSandboxContract.js

@@ -0,0 +1,111 @@
+export const MSWARM_ARTIFACT_SANDBOX_SCHEMA_VERSION = "2026-06-14";
+const WINDOWS_DRIVE_PREFIX = /^[a-zA-Z]:[\\/]/;
+const URL_SCHEME_PREFIX = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+export function normalizeMswarmSafeRelativePath(path) {
+    if (typeof path !== "string" || path.trim().length === 0) {
+        return { ok: false, reason: "path_required" };
+    }
+    const raw = path.trim();
+    if (raw.includes("\0")) {
+        return { ok: false, reason: "null_byte" };
+    }
+    if (raw.includes("\\")) {
+        return { ok: false, reason: "backslash_not_allowed" };
+    }
+    if (raw.startsWith("/") || raw.startsWith("//") || WINDOWS_DRIVE_PREFIX.test(raw)) {
+        return { ok: false, reason: "absolute_path_not_allowed" };
+    }
+    if (URL_SCHEME_PREFIX.test(raw)) {
+        return { ok: false, reason: "uri_path_not_allowed" };
+    }
+    const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
+    if (parts.length === 0) {
+        return { ok: false, reason: "path_required" };
+    }
+    for (const part of parts) {
+        if (part === "..") {
+            return { ok: false, reason: "parent_path_not_allowed" };
+        }
+        if (part.length > 255) {
+            return { ok: false, reason: "path_segment_too_long" };
+        }
+    }
+    return { ok: true, normalized: parts.join("/") };
+}
+export function assertMswarmSafeRelativePath(path, label = "path") {
+    const result = normalizeMswarmSafeRelativePath(path);
+    if (!result.ok || !result.normalized) {
+        throw new Error(`${label}_${result.reason || "invalid"}`);
+    }
+    return result.normalized;
+}
+export function validateMswarmOutputSpecPath(output) {
+    return normalizeMswarmSafeRelativePath(output.path);
+}
+export function validateMswarmArchiveEntry(entry) {
+    const type = entry.type || "file";
+    if (type === "symlink" || type === "hardlink" || type === "device" || type === "other") {
+        return { ok: false, reason: `archive_${type}_not_allowed` };
+    }
+    if (Number.isFinite(entry.size_bytes) && entry.size_bytes !== undefined && entry.size_bytes < 0) {
+        return { ok: false, reason: "negative_size_not_allowed" };
+    }
+    return normalizeMswarmSafeRelativePath(entry.path);
+}
+export function defaultMswarmArtifactAccessPolicy(visibility = "owner-local") {
+    return {
+        visibility,
+        read_by: visibility === "tenant-scoped" ? ["runner", "tenant", "gateway"] : ["runner", "owner"],
+        write_by: visibility === "tenant-scoped" ? ["runner", "gateway"] : ["runner", "owner"],
+    };
+}
+export function defaultMswarmArtifactRetentionPolicy(retainForSeconds = 86400) {
+    return {
+        retain_for_seconds: retainForSeconds,
+    };
+}
+export function buildMswarmLocalArtifactUri(jobId, relativePath) {
+    const normalizedJobId = assertMswarmSafeRelativePath(jobId.replace(/[^a-zA-Z0-9_.-]/g, "_"), "job_id");
+    const normalizedPath = assertMswarmSafeRelativePath(relativePath, "artifact_path");
+    return `artifact://local/${normalizedJobId}/${normalizedPath}`;
+}
+export function buildMswarmSandboxProfile(input) {
+    const containerized = input.containerized === true;
+    const gpu = input.gpu || "none";
+    const name = containerized
+        ? gpu === "nvidia"
+            ? "container-nvidia"
+            : "container-cpu"
+        : "owner-local-process";
+    return {
+        schema_version: MSWARM_ARTIFACT_SANDBOX_SCHEMA_VERSION,
+        name,
+        trust_mode: input.policy.trust_mode,
+        network: input.policy.network || "none",
+        allow_raw_command: false,
+        filesystem: {
+            working_directory: "per-job",
+            inputs: "read-only",
+            outputs: "write-only",
+            allow_host_paths: false,
+            validate_output_paths: true,
+            validate_archive_entries: true,
+        },
+        container: {
+            enabled: containerized,
+            rootless: true,
+            user: "65532:65532",
+            privileged: false,
+            read_only_root_fs: true,
+            gpu,
+            ...(input.policy.allowed_images?.length ? { allowed_images: [...input.policy.allowed_images] } : {}),
+        },
+        limits: {
+            timeout_sec: input.limits?.timeout_sec,
+            max_stdout_bytes: input.limits?.max_stdout_bytes,
+            max_stderr_bytes: input.limits?.max_stderr_bytes,
+            max_output_bytes: input.limits?.max_output_bytes,
+            max_artifact_bytes: input.policy.max_artifact_bytes,
+        },
+    };
+}

package/dist/mswarm/CapabilityContract.d.ts

@@ -0,0 +1,136 @@
+import type { MswarmGpuVendor, MswarmJobTrustMode, MswarmJobType } from "./GenericJobContract.js";
+export declare const MSWARM_CAPABILITY_SCHEMA_VERSION: "2026-06-14";
+export declare const MSWARM_CAPABILITY_PROBE_STATUSES: readonly ["available", "missing", "error", "unknown"];
+export type MswarmCapabilitySchemaVersion = typeof MSWARM_CAPABILITY_SCHEMA_VERSION;
+export type MswarmCapabilityProbeStatus = (typeof MSWARM_CAPABILITY_PROBE_STATUSES)[number];
+export type MswarmSoftwareProbeName = "docker" | "docker-nvidia" | "blender" | "ffmpeg";
+export type MswarmPublicVramTier = "none" | "lt8" | "8-15" | "16-31" | "32plus";
+export interface MswarmSoftwareProbeResult {
+    name: MswarmSoftwareProbeName;
+    status: MswarmCapabilityProbeStatus;
+    version?: string;
+    message?: string;
+}
+export interface MswarmGpuDeviceCapability {
+    id: string;
+    vendor: MswarmGpuVendor;
+    name?: string;
+    vram_gb?: number;
+    driver_version?: string;
+    cuda_version?: string;
+    compute_capability?: string;
+    capabilities?: string[];
+}
+export interface MswarmGpuCapabilityProbe {
+    status: MswarmCapabilityProbeStatus;
+    count: number;
+    vendors: MswarmGpuVendor[];
+    devices: MswarmGpuDeviceCapability[];
+    cuda_versions?: string[];
+    max_vram_gb?: number;
+    message?: string;
+}
+export interface MswarmRunnerCatalogCapability {
+    job_type: MswarmJobType;
+    runner: string;
+    trust_modes: MswarmJobTrustMode[];
+    required_capabilities?: string[];
+}
+export interface MswarmNodeCapabilitySnapshot {
+    schema_version: MswarmCapabilitySchemaVersion;
+    snapshot_id: string;
+    captured_at: string;
+    node_id?: string;
+    platform?: string;
+    arch?: string;
+    generic_jobs_enabled: boolean;
+    job_types: MswarmJobType[];
+    trust_modes: MswarmJobTrustMode[];
+    gpu: MswarmGpuCapabilityProbe;
+    software: Record<MswarmSoftwareProbeName, MswarmSoftwareProbeResult>;
+    runner_catalog: MswarmRunnerCatalogCapability[];
+    diagnostics?: Array<{
+        name: string;
+        status: Exclude<MswarmCapabilityProbeStatus, "available">;
+        message?: string;
+    }>;
+}
+export interface MswarmSchedulerMatchInput {
+    schema_version: MswarmCapabilitySchemaVersion;
+    snapshot_id: string;
+    node_id?: string;
+    updated_at: string;
+    generic_jobs_enabled: boolean;
+    available_job_types: MswarmJobType[];
+    trust_modes: MswarmJobTrustMode[];
+    resources: {
+        gpu_count: number;
+        gpu_vendors: MswarmGpuVendor[];
+        max_vram_gb?: number;
+        has_cuda: boolean;
+        software: {
+            docker_nvidia: boolean;
+            blender: boolean;
+            ffmpeg: boolean;
+        };
+    };
+    capabilities: string[];
+}
+export interface MswarmPublicCapabilityProjection {
+    schema_version: MswarmCapabilitySchemaVersion;
+    snapshot_id: string;
+    captured_at: string;
+    generic_jobs_enabled: boolean;
+    job_types: MswarmJobType[];
+    accelerators: {
+        gpu: {
+            available: boolean;
+            count: number;
+            vendors: MswarmGpuVendor[];
+            cuda: boolean;
+            vram_tier: MswarmPublicVramTier;
+        };
+    };
+    software: {
+        docker_nvidia: {
+            available: boolean;
+            status: MswarmCapabilityProbeStatus;
+        };
+        blender: {
+            available: boolean;
+            status: MswarmCapabilityProbeStatus;
+        };
+        ffmpeg: {
+            available: boolean;
+            status: MswarmCapabilityProbeStatus;
+        };
+    };
+    capabilities: string[];
+}
+export interface MswarmPrivateCapabilityCatalogEntry {
+    node_id?: string;
+    snapshot_id: string;
+    captured_at: string;
+    snapshot: MswarmNodeCapabilitySnapshot;
+    scheduler_match: MswarmSchedulerMatchInput;
+    public_projection: MswarmPublicCapabilityProjection;
+}
+export interface MswarmCapabilitySignature {
+    alg: "HS256";
+    value: string;
+    signed_at: string;
+    key_id?: string;
+}
+export interface MswarmSignedCapabilityPayload {
+    schema_version: MswarmCapabilitySchemaVersion;
+    snapshot_id: string;
+    private_catalog_entry: MswarmPrivateCapabilityCatalogEntry;
+    scheduler_match: MswarmSchedulerMatchInput;
+    public_projection: MswarmPublicCapabilityProjection;
+    signature: MswarmCapabilitySignature;
+}
+export declare function buildMswarmCapabilityNames(snapshot: MswarmNodeCapabilitySnapshot): string[];
+export declare function buildMswarmSchedulerMatchInput(snapshot: MswarmNodeCapabilitySnapshot): MswarmSchedulerMatchInput;
+export declare function projectMswarmPublicCapabilities(snapshot: MswarmNodeCapabilitySnapshot): MswarmPublicCapabilityProjection;
+export declare function buildMswarmPrivateCapabilityCatalogEntry(snapshot: MswarmNodeCapabilitySnapshot): MswarmPrivateCapabilityCatalogEntry;
+//# sourceMappingURL=CapabilityContract.d.ts.map

package/dist/mswarm/CapabilityContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityContract.d.ts","sourceRoot":"","sources":["../../src/mswarm/CapabilityContract.ts"],"names":[],"mappings":"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"}

package/dist/mswarm/CapabilityContract.js

@@ -0,0 +1,128 @@
+export const MSWARM_CAPABILITY_SCHEMA_VERSION = "2026-06-14";
+export const MSWARM_CAPABILITY_PROBE_STATUSES = [
+    "available",
+    "missing",
+    "error",
+    "unknown",
+];
+function sortedUnique(values) {
+    return Array.from(new Set(values.filter((value) => typeof value === "string" && value.length > 0))).sort();
+}
+function softwareAvailable(result) {
+    return result?.status === "available";
+}
+function hasCuda(snapshot) {
+    return (Boolean(snapshot.gpu.cuda_versions?.length) ||
+        snapshot.gpu.devices.some((device) => {
+            const caps = device.capabilities || [];
+            return Boolean(device.cuda_version) || caps.some((capability) => capability.toLowerCase() === "cuda");
+        }));
+}
+function publicVramTier(maxVramGb) {
+    if (!Number.isFinite(maxVramGb) || !maxVramGb || maxVramGb <= 0)
+        return "none";
+    if (maxVramGb < 8)
+        return "lt8";
+    if (maxVramGb < 16)
+        return "8-15";
+    if (maxVramGb < 32)
+        return "16-31";
+    return "32plus";
+}
+export function buildMswarmCapabilityNames(snapshot) {
+    const names = [];
+    if (snapshot.generic_jobs_enabled) {
+        names.push("generic_jobs");
+    }
+    for (const jobType of snapshot.job_types) {
+        names.push(`job_type:${jobType}`);
+    }
+    if (snapshot.gpu.status === "available" && snapshot.gpu.count > 0) {
+        names.push("gpu");
+        for (const vendor of snapshot.gpu.vendors) {
+            names.push(`gpu.${vendor}`);
+        }
+    }
+    if (hasCuda(snapshot)) {
+        names.push("cuda");
+    }
+    if (softwareAvailable(snapshot.software.docker)) {
+        names.push("software.docker");
+    }
+    if (softwareAvailable(snapshot.software["docker-nvidia"])) {
+        names.push("docker.nvidia");
+    }
+    if (softwareAvailable(snapshot.software.blender)) {
+        names.push("software.blender");
+    }
+    if (softwareAvailable(snapshot.software.ffmpeg)) {
+        names.push("software.ffmpeg");
+    }
+    return sortedUnique(names);
+}
+export function buildMswarmSchedulerMatchInput(snapshot) {
+    return {
+        schema_version: MSWARM_CAPABILITY_SCHEMA_VERSION,
+        snapshot_id: snapshot.snapshot_id,
+        node_id: snapshot.node_id,
+        updated_at: snapshot.captured_at,
+        generic_jobs_enabled: snapshot.generic_jobs_enabled,
+        available_job_types: sortedUnique(snapshot.job_types),
+        trust_modes: sortedUnique(snapshot.trust_modes),
+        resources: {
+            gpu_count: snapshot.gpu.count,
+            gpu_vendors: sortedUnique(snapshot.gpu.vendors),
+            ...(Number.isFinite(snapshot.gpu.max_vram_gb) ? { max_vram_gb: snapshot.gpu.max_vram_gb } : {}),
+            has_cuda: hasCuda(snapshot),
+            software: {
+                docker_nvidia: softwareAvailable(snapshot.software["docker-nvidia"]),
+                blender: softwareAvailable(snapshot.software.blender),
+                ffmpeg: softwareAvailable(snapshot.software.ffmpeg),
+            },
+        },
+        capabilities: buildMswarmCapabilityNames(snapshot),
+    };
+}
+export function projectMswarmPublicCapabilities(snapshot) {
+    return {
+        schema_version: MSWARM_CAPABILITY_SCHEMA_VERSION,
+        snapshot_id: snapshot.snapshot_id,
+        captured_at: snapshot.captured_at,
+        generic_jobs_enabled: snapshot.generic_jobs_enabled,
+        job_types: sortedUnique(snapshot.job_types),
+        accelerators: {
+            gpu: {
+                available: snapshot.gpu.status === "available" && snapshot.gpu.count > 0,
+                count: snapshot.gpu.count,
+                vendors: sortedUnique(snapshot.gpu.vendors),
+                cuda: hasCuda(snapshot),
+                vram_tier: publicVramTier(snapshot.gpu.max_vram_gb),
+            },
+        },
+        software: {
+            docker_nvidia: {
+                available: softwareAvailable(snapshot.software["docker-nvidia"]),
+                status: snapshot.software["docker-nvidia"].status,
+            },
+            blender: {
+                available: softwareAvailable(snapshot.software.blender),
+                status: snapshot.software.blender.status,
+            },
+            ffmpeg: {
+                available: softwareAvailable(snapshot.software.ffmpeg),
+                status: snapshot.software.ffmpeg.status,
+            },
+        },
+        capabilities: buildMswarmCapabilityNames(snapshot),
+    };
+}
+export function buildMswarmPrivateCapabilityCatalogEntry(snapshot) {
+    return {
+        node_id: snapshot.node_id,
+        snapshot_id: snapshot.snapshot_id,
+        captured_at: snapshot.captured_at,
+        snapshot,
+        scheduler_match: buildMswarmSchedulerMatchInput(snapshot),
+        public_projection: projectMswarmPublicCapabilities(snapshot),
+    };
+}