@norskvideo/ctl-product-template-schema 0.1.11 → 0.1.13

package/index.d.ts

@@ -48,6 +48,56 @@ export declare const ProductTemplateSideloadSchema: z.ZodObject<{
     llmVenv: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ProductTemplateSideload = z.infer<typeof ProductTemplateSideloadSchema>;
+export declare const ProductTemplateRequirementsSchema: z.ZodObject<{
+    capacity: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            default: "default";
+            fixed: "fixed";
+            required: "required";
+        }>;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cores: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            default: "default";
+            fixed: "fixed";
+            required: "required";
+        }>;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    gpu: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            default: "default";
+            fixed: "fixed";
+            required: "required";
+        }>;
+        value: z.ZodOptional<z.ZodObject<{
+            capacity: z.ZodOptional<z.ZodNumber>;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            default: "default";
+            fixed: "fixed";
+            required: "required";
+        }>;
+        value: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            count: z.ZodOptional<z.ZodNumber>;
+            attributeMatches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    hostPorts: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            default: "default";
+            fixed: "fixed";
+            required: "required";
+        }>;
+        value: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProductTemplateRequirements = z.infer<typeof ProductTemplateRequirementsSchema>;
 export declare const ProductTemplateManifestSchema: z.ZodObject<{
     productTemplateSchemaVersion: z.ZodLiteral<1>;
     productName: z.ZodString;
@@ -106,6 +156,55 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
             default: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    requirements: z.ZodOptional<z.ZodObject<{
+        capacity: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        cores: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        gpu: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodObject<{
+                capacity: z.ZodOptional<z.ZodNumber>;
+                model: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodOptional<z.ZodNumber>;
+                attributeMatches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        hostPorts: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     allocatedPorts: z.ZodOptional<z.ZodArray<z.ZodObject<{
         param: z.ZodString;
         protocol: z.ZodEnum<{
@@ -224,6 +323,55 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
                 default: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        requirements: z.ZodOptional<z.ZodObject<{
+            capacity: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    default: "default";
+                    fixed: "fixed";
+                    required: "required";
+                }>;
+                value: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            cores: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    default: "default";
+                    fixed: "fixed";
+                    required: "required";
+                }>;
+                value: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            gpu: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    default: "default";
+                    fixed: "fixed";
+                    required: "required";
+                }>;
+                value: z.ZodOptional<z.ZodObject<{
+                    capacity: z.ZodOptional<z.ZodNumber>;
+                    model: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            capabilities: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    default: "default";
+                    fixed: "fixed";
+                    required: "required";
+                }>;
+                value: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    count: z.ZodOptional<z.ZodNumber>;
+                    attributeMatches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            hostPorts: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    default: "default";
+                    fixed: "fixed";
+                    required: "required";
+                }>;
+                value: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         allocatedPorts: z.ZodOptional<z.ZodArray<z.ZodObject<{
             param: z.ZodString;
             protocol: z.ZodEnum<{

package/index.js

@@ -138,6 +138,69 @@ export const ProductTemplateSideloadSchema = z
     }),
 })
     .meta({ id: "ProductTemplateSideload", outputId: "ProductTemplateSideload" });
+// Placement requirements guidance (requirements-authoring.md). Each dimension
+// the placer reasons over — capacity (vCPUs), cores, GPU, capabilities, host
+// ports — is optionally declared with a `mode`:
+//   fixed    — pinned; the operator can't change it (value required).
+//   default  — a pre-filled starting value the operator may override.
+//   required — the product can't know it (e.g. a runtime-authored Studio
+//              workflow); the operator MUST supply it at create (value forbidden).
+// An absent dimension is never asked for. The manifest only offers guidance;
+// authoritative values are resolved at create time (template-baked or
+// operator-entered) and projected into the job's JobRequirements.
+const ProductTemplateRequirementModeSchema = z.enum(["fixed", "default", "required"]);
+// Wrap a dimension's value schema with the mode/value contract: fixed/default
+// must carry a value, required must not (the operator supplies it).
+function requirementDimension(value, hasValue = () => true) {
+    return z.object({ mode: ProductTemplateRequirementModeSchema, value: value.optional() }).superRefine((d, ctx) => {
+        if (d.mode === "required" && d.value !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["value"],
+                message: "a `required` dimension must not declare a value — the operator supplies it at create",
+            });
+        }
+        const present = d.value !== undefined && hasValue(d.value);
+        if ((d.mode === "fixed" || d.mode === "default") && !present) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["value"],
+                message: "a `fixed`/`default` dimension must declare a value",
+            });
+        }
+    });
+}
+const ProductTemplateCapabilityRequirementSchema = z.object({
+    name: z.string(),
+    count: z.number().int().min(1).optional().meta({ description: "How many of this capability; default 1" }),
+    attributeMatches: z
+        .record(z.string(), z.string())
+        .optional()
+        .meta({ description: "Each key must equal the matched capability's attribute, e.g. { model: 'RTX 4090' }" }),
+});
+const ProductTemplateGpuRequirementSchema = z.object({
+    capacity: z.number().positive().optional().meta({ description: "Fractional GPU reference units" }),
+    model: z.string().optional().meta({ description: "GPU model match, e.g. 'RTX 4090'" }),
+});
+export const ProductTemplateRequirementsSchema = z
+    .object({
+    capacity: requirementDimension(z.number().positive()).optional().meta({
+        description: "CPU capacity in vCPUs — the primary placement dimension (capacity ≡ vCPUs).",
+    }),
+    cores: requirementDimension(z.number().int().positive()).optional().meta({
+        description: "Pinned cpuset core count (distinct from capacity).",
+    }),
+    gpu: requirementDimension(ProductTemplateGpuRequirementSchema, (v) => v.capacity !== undefined || v.model !== undefined)
+        .optional()
+        .meta({ description: "Fractional GPU need (capacity and/or model)." }),
+    capabilities: requirementDimension(z.array(ProductTemplateCapabilityRequirementSchema).min(1))
+        .optional()
+        .meta({ description: "Counted/exclusive hardware & software capabilities (nvidia-gpu, quadra, decklink, …)." }),
+    hostPorts: requirementDimension(z.array(z.string().regex(/^\d+\/(tcp|udp)$/i, "canonical PORT/proto token, e.g. 5001/udp")).min(1))
+        .optional()
+        .meta({ description: "Fixed host sockets the job binds (exclusive)." }),
+})
+    .meta({ id: "ProductTemplateRequirements", outputId: "ProductTemplateRequirements" });
 export const ProductTemplateManifestSchema = z
     .object({
     productTemplateSchemaVersion: z.literal(1),
@@ -161,6 +224,9 @@ export const ProductTemplateManifestSchema = z
     advanced: ProductTemplateAdvancedSchema.optional().meta({
         description: "Settings-backed runner knobs the operator may override per instance. Key presence opts the knob into the launch form; `default` pre-fills it (else the runner's daemon-wide default applies).",
     }),
+    requirements: ProductTemplateRequirementsSchema.optional().meta({
+        description: "Placement requirements guidance. Each dimension (capacity/cores/gpu/capabilities/hostPorts) declares fixed (pinned) / default (pre-filled, overridable) / required (operator must supply at create). Absent dimensions are never asked for. Authoritative values are resolved at create time and drive placement; this is guidance only.",
+    }),
     allocatedPorts: z.array(ProductTemplateAllocatedPortSchema).optional().meta({
         description: "Host-port bindings whose value rides a product-template parameter. Opt-in per launch via the param value: absent = closed, 'auto' = allocate a free port from `preferred`, number = use it. When opened the port is published as a managed host binding and surfaced to the containers via compose interpolation. Alongside the per-param scalars the runner sets NORSK_ALLOCATED_PORTS: a JSON object keyed by param, each value {port, protocol, service?}, describing every opened port ('{}' when none opted in; unset when nothing is declared) — so a product needing the allocation as data maps one var instead of folding scalars into JSON via interpolation.",
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "exports": {
     ".": {