@mcoda/shared 0.1.75 → 0.1.78

package/dist/mswarm/LifecycleContract.d.ts

@@ -0,0 +1,122 @@
+import type { MswarmArtifactRef, MswarmGenericJobValidationIssue, MswarmJobEvent, MswarmJobRequest, MswarmJobResult, MswarmJobType } from "./GenericJobContract.js";
+export declare const MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION: "2026-06-14";
+export declare const MSWARM_GENERIC_JOB_LIFECYCLE_STATES: readonly ["queued", "scheduled", "running", "retrying", "succeeded", "failed", "cancelled", "expired", "blocked"];
+export type MswarmGenericJobLifecycleState = (typeof MSWARM_GENERIC_JOB_LIFECYCLE_STATES)[number];
+export declare const MSWARM_GENERIC_JOB_TERMINAL_LIFECYCLE_STATES: readonly ["succeeded", "failed", "cancelled", "expired", "blocked"];
+export type MswarmGenericJobTerminalLifecycleState = (typeof MSWARM_GENERIC_JOB_TERMINAL_LIFECYCLE_STATES)[number];
+export type MswarmGenericJobBackpressureReason = "no_capable_node" | "node_at_capacity" | "tenant_reserved" | "policy_recheck_failed" | "capability_recheck_failed";
+export type MswarmGenericJobAuditAction = "job_created" | "job_idempotent_reused" | "job_queued" | "job_scheduled" | "job_started" | "job_event_recorded" | "job_completed" | "job_cancel_requested" | "job_cancelled" | "job_retry_scheduled" | "job_blocked" | "reservation_created" | "reservation_released" | "envelope_issued";
+export interface MswarmGenericJobRetryPolicy {
+    max_retries: number;
+    retry_count: number;
+    retryable_error_codes?: string[];
+    next_retry_at?: string;
+}
+export interface MswarmGenericJobBackpressure {
+    reason: MswarmGenericJobBackpressureReason;
+    message: string;
+    retry_after_ms?: number;
+}
+export interface MswarmGenericJobReservation {
+    node_id: string;
+    tenant_id: string;
+    job_id: string;
+    request_id: string;
+    reserved_at: string;
+    released_at?: string;
+    resources?: {
+        gpu_count?: number;
+        cpu_cores?: number;
+        memory_gb?: number;
+        disk_gb?: number;
+    };
+}
+export interface MswarmGenericJobEnvelopeDescriptor {
+    schema_version: typeof MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION;
+    job_id: string;
+    request_id: string;
+    node_id: string;
+    job_type: MswarmJobType;
+    job_schema_version: MswarmJobRequest["schema_version"];
+    scope: "self_hosted.generic_job.invoke";
+    issued_at: string;
+    expires_at: string;
+    token_sha256?: string;
+}
+export interface MswarmGenericJobRecord {
+    schema_version: typeof MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION;
+    job_id: string;
+    request_id: string;
+    tenant_id: string;
+    node_id?: string;
+    state: MswarmGenericJobLifecycleState;
+    job: MswarmJobRequest;
+    idempotency_key?: string;
+    created_at: string;
+    updated_at: string;
+    queued_at?: string;
+    scheduled_at?: string;
+    started_at?: string;
+    finished_at?: string;
+    retry: MswarmGenericJobRetryPolicy;
+    reservation?: MswarmGenericJobReservation;
+    backpressure?: MswarmGenericJobBackpressure;
+    envelope?: MswarmGenericJobEnvelopeDescriptor;
+    validation_issues?: MswarmGenericJobValidationIssue[];
+    result?: MswarmJobResult;
+    artifacts?: MswarmArtifactRef[];
+}
+export interface MswarmGenericJobLogRecord {
+    job_id: string;
+    sequence: number;
+    timestamp: string;
+    stream: "stdout" | "stderr";
+    message: string;
+    truncated?: boolean;
+}
+export interface MswarmGenericJobAuditEvent {
+    schema_version: typeof MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION;
+    audit_id: string;
+    job_id: string;
+    request_id?: string;
+    tenant_id?: string;
+    node_id?: string;
+    action: MswarmGenericJobAuditAction;
+    timestamp: string;
+    details?: Record<string, unknown>;
+}
+export interface MswarmGenericJobLifecycleSnapshot {
+    job: MswarmGenericJobRecord;
+    events: MswarmJobEvent[];
+    logs: MswarmGenericJobLogRecord[];
+    artifacts: MswarmArtifactRef[];
+    audit: MswarmGenericJobAuditEvent[];
+}
+export declare function isMswarmTerminalLifecycleState(state: MswarmGenericJobLifecycleState): state is MswarmGenericJobTerminalLifecycleState;
+export declare function isMswarmLifecycleStateTransitionAllowed(from: MswarmGenericJobLifecycleState, to: MswarmGenericJobLifecycleState): boolean;
+export declare function buildMswarmGenericJobEnvelopeDescriptor(input: {
+    jobId: string;
+    requestId: string;
+    nodeId: string;
+    job: MswarmJobRequest;
+    issuedAt: string;
+    expiresAt: string;
+    tokenSha256?: string;
+}): MswarmGenericJobEnvelopeDescriptor;
+export declare function buildMswarmGenericJobAuditEvent(input: {
+    auditId: string;
+    jobId: string;
+    requestId?: string;
+    tenantId?: string;
+    nodeId?: string;
+    action: MswarmGenericJobAuditAction;
+    timestamp: string;
+    details?: Record<string, unknown>;
+}): MswarmGenericJobAuditEvent;
+export declare function normalizeMswarmGenericJobIdempotencyKey(input: {
+    tenantId: string;
+    idempotencyKey?: string;
+    jobId?: string;
+    requestId?: string;
+}): string;
+//# sourceMappingURL=LifecycleContract.d.ts.map

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

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

package/dist/mswarm/LifecycleContract.js

@@ -0,0 +1,68 @@
+export const MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION = "2026-06-14";
+export const MSWARM_GENERIC_JOB_LIFECYCLE_STATES = [
+    "queued",
+    "scheduled",
+    "running",
+    "retrying",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "expired",
+    "blocked",
+];
+export const MSWARM_GENERIC_JOB_TERMINAL_LIFECYCLE_STATES = [
+    "succeeded",
+    "failed",
+    "cancelled",
+    "expired",
+    "blocked",
+];
+const TERMINAL_LIFECYCLE_STATE_SET = new Set(MSWARM_GENERIC_JOB_TERMINAL_LIFECYCLE_STATES);
+const ALLOWED_LIFECYCLE_TRANSITIONS = {
+    queued: ["scheduled", "cancelled", "expired", "blocked"],
+    scheduled: ["running", "queued", "cancelled", "expired", "blocked"],
+    running: ["succeeded", "failed", "cancelled", "retrying", "expired"],
+    retrying: ["queued", "cancelled", "expired", "blocked"],
+    succeeded: [],
+    failed: [],
+    cancelled: [],
+    expired: [],
+    blocked: [],
+};
+export function isMswarmTerminalLifecycleState(state) {
+    return TERMINAL_LIFECYCLE_STATE_SET.has(state);
+}
+export function isMswarmLifecycleStateTransitionAllowed(from, to) {
+    return from === to || ALLOWED_LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+export function buildMswarmGenericJobEnvelopeDescriptor(input) {
+    return {
+        schema_version: MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION,
+        job_id: input.jobId,
+        request_id: input.requestId,
+        node_id: input.nodeId,
+        job_type: input.job.job_type,
+        job_schema_version: input.job.schema_version,
+        scope: "self_hosted.generic_job.invoke",
+        issued_at: input.issuedAt,
+        expires_at: input.expiresAt,
+        ...(input.tokenSha256 ? { token_sha256: input.tokenSha256 } : {}),
+    };
+}
+export function buildMswarmGenericJobAuditEvent(input) {
+    return {
+        schema_version: MSWARM_JOB_LIFECYCLE_SCHEMA_VERSION,
+        audit_id: input.auditId,
+        job_id: input.jobId,
+        ...(input.requestId ? { request_id: input.requestId } : {}),
+        ...(input.tenantId ? { tenant_id: input.tenantId } : {}),
+        ...(input.nodeId ? { node_id: input.nodeId } : {}),
+        action: input.action,
+        timestamp: input.timestamp,
+        ...(input.details ? { details: input.details } : {}),
+    };
+}
+export function normalizeMswarmGenericJobIdempotencyKey(input) {
+    const key = input.idempotencyKey || input.jobId || input.requestId || "";
+    return `${input.tenantId}:${key}`.trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/shared",
-  "version": "0.1.75",
+  "version": "0.1.78",
   "description": "Shared utilities and schemas for mcoda.",
   "type": "module",
   "main": "dist/index.js",