@wardby/cli 0.2.0 → 0.3.0

package/dist/coding/services/builtins.js

@@ -0,0 +1,85 @@
+function postgres(version, digest) {
+    return {
+        name: "postgres",
+        version,
+        kind: "sidecar",
+        image: `docker.io/library/postgres@${digest}`,
+        port: 5432,
+        serviceEnv: {
+            POSTGRES_USER: "test",
+            POSTGRES_PASSWORD: "test",
+            POSTGRES_DB: "test",
+            PGDATA: "/var/lib/postgresql/data/pgdata",
+        },
+        testEnv: {
+            DATABASE_URL: "postgres://test:test@127.0.0.1:5432/test",
+            PGHOST: "127.0.0.1",
+            PGPORT: "5432",
+            PGUSER: "test",
+            PGPASSWORD: "test",
+            PGDATABASE: "test",
+        },
+        readiness: {
+            command: ["pg_isready", "-h", "127.0.0.1", "-p", "5432", "-U", "test", "-d", "test"],
+            periodSeconds: 2,
+            timeoutSeconds: 2,
+            failureThreshold: 30,
+        },
+        resources: { cpuMillicores: 500, memoryMib: 512, diskMib: 1024 },
+        dataPath: "/var/lib/postgresql/data",
+        writablePaths: ["/var/run/postgresql", "/tmp"],
+    };
+}
+export const BUILTIN_CODING_SERVICES = Object.freeze([
+    postgres("15", "sha256:724292da1f2e50bdccfc3302ce75bbba7f4a6076701b588cc795fcac65683550"),
+    postgres("16", "sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54"),
+    postgres("17", "sha256:d74eeac9a635390a49bc21bd49fccd973de707e2a53a76ac49b552b8712ec46f"),
+    {
+        name: "redis",
+        version: "7",
+        kind: "sidecar",
+        image: "docker.io/library/redis@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f",
+        port: 6379,
+        serviceEnv: {},
+        testEnv: { REDIS_URL: "redis://127.0.0.1:6379/0", REDIS_HOST: "127.0.0.1", REDIS_PORT: "6379" },
+        readiness: {
+            command: ["redis-cli", "-h", "127.0.0.1", "-p", "6379", "ping"],
+            periodSeconds: 1,
+            timeoutSeconds: 2,
+            failureThreshold: 30,
+        },
+        resources: { cpuMillicores: 250, memoryMib: 256, diskMib: 256 },
+        dataPath: "/data",
+        writablePaths: [],
+    },
+    {
+        name: "mysql",
+        version: "8",
+        kind: "sidecar",
+        image: "docker.io/library/mysql@sha256:0744ee5ef89ce6ccfa13de3e579fe6b9e27f93dd70da9c06d2c908b1b193fb8d",
+        port: 3306,
+        serviceEnv: {
+            MYSQL_ROOT_PASSWORD: "test",
+            MYSQL_DATABASE: "test",
+            MYSQL_USER: "test",
+            MYSQL_PASSWORD: "test",
+        },
+        testEnv: {
+            DATABASE_URL: "mysql://test:test@127.0.0.1:3306/test",
+            MYSQL_HOST: "127.0.0.1",
+            MYSQL_TCP_PORT: "3306",
+            MYSQL_USER: "test",
+            MYSQL_PASSWORD: "test",
+            MYSQL_DATABASE: "test",
+        },
+        readiness: {
+            command: ["mysqladmin", "ping", "-h", "127.0.0.1", "-P", "3306", "-utest", "-ptest", "--silent"],
+            periodSeconds: 2,
+            timeoutSeconds: 3,
+            failureThreshold: 45,
+        },
+        resources: { cpuMillicores: 500, memoryMib: 1024, diskMib: 2048 },
+        dataPath: "/var/lib/mysql",
+        writablePaths: ["/var/run/mysqld", "/tmp"],
+    },
+]);

package/dist/coding/services/catalog.d.ts

@@ -0,0 +1,443 @@
+/**
+ * The coding-run service catalog (docs/coding-services.md): what a repository's
+ * .wardby/services.yaml may name. An entry is admin-managed, trusted data: a
+ * digest-pinned image, the environment it starts with, the variables it hands
+ * the agent's shells, how to tell it is ready, and what it may use. Repository
+ * content only ever names an entry; it never supplies any of these.
+ */
+import { z } from "zod";
+/** "sidecar": a fresh instance in each run's pod. "external" is reserved for shared services reached through the proxy. */
+export declare const CODING_SERVICE_KINDS: readonly ["sidecar"];
+/** How many service names one agent may be allowed. */
+export declare const MAX_AGENT_SERVICES = 16;
+export declare const MAX_SERVICE_ENV = 32;
+export declare const codingServiceNameSchema: z.ZodString;
+export declare const codingServiceVersionSchema: z.ZodString;
+export declare const CodingServiceReadinessSchema: z.ZodObject<{
+    command: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">;
+    periodSeconds: z.ZodNumber;
+    timeoutSeconds: z.ZodNumber;
+    failureThreshold: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    command: string[];
+    periodSeconds: number;
+    timeoutSeconds: number;
+    failureThreshold: number;
+}, {
+    command: string[];
+    periodSeconds: number;
+    timeoutSeconds: number;
+    failureThreshold: number;
+}>;
+export declare const CodingServiceResourcesSchema: z.ZodObject<{
+    cpuMillicores: z.ZodNumber;
+    memoryMib: z.ZodNumber;
+    diskMib: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    cpuMillicores: number;
+    memoryMib: number;
+    diskMib: number;
+}, {
+    cpuMillicores: number;
+    memoryMib: number;
+    diskMib: number;
+}>;
+/** One run's snapshot of an entry: what dispatch stores on CodingRun.services and the launcher reads. */
+export declare const ResolvedCodingServiceSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    image: z.ZodEffects<z.ZodString, string, string>;
+    port: z.ZodNumber;
+    serviceEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>, Record<string, string>, Record<string, string>>>;
+    testEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>>;
+    readiness: z.ZodObject<{
+        command: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">;
+        periodSeconds: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+        failureThreshold: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }>;
+    resources: z.ZodObject<{
+        cpuMillicores: z.ZodNumber;
+        memoryMib: z.ZodNumber;
+        diskMib: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }>;
+    dataPath: z.ZodEffects<z.ZodString, string, string>;
+    writablePaths: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+}>, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+}>;
+/** A catalog entry, as create_service takes it and the CodingService table holds it. */
+export declare const CodingServiceDefinitionSchema: z.ZodEffects<z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["sidecar"]>>;
+    name: z.ZodString;
+    version: z.ZodString;
+    image: z.ZodEffects<z.ZodString, string, string>;
+    port: z.ZodNumber;
+    serviceEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>, Record<string, string>, Record<string, string>>>;
+    testEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>>;
+    readiness: z.ZodObject<{
+        command: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">;
+        periodSeconds: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+        failureThreshold: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }>;
+    resources: z.ZodObject<{
+        cpuMillicores: z.ZodNumber;
+        memoryMib: z.ZodNumber;
+        diskMib: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }>;
+    dataPath: z.ZodEffects<z.ZodString, string, string>;
+    writablePaths: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+    kind: "sidecar";
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+    kind?: "sidecar" | undefined;
+}>, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+    kind: "sidecar";
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+    kind?: "sidecar" | undefined;
+}>;
+export type ResolvedCodingService = z.output<typeof ResolvedCodingServiceSchema>;
+export type CodingServiceDefinition = z.output<typeof CodingServiceDefinitionSchema>;
+export declare const StoredCodingServicesSchema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    image: z.ZodEffects<z.ZodString, string, string>;
+    port: z.ZodNumber;
+    serviceEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>, Record<string, string>, Record<string, string>>>;
+    testEnv: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>>;
+    readiness: z.ZodObject<{
+        command: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">;
+        periodSeconds: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+        failureThreshold: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }, {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    }>;
+    resources: z.ZodObject<{
+        cpuMillicores: z.ZodNumber;
+        memoryMib: z.ZodNumber;
+        diskMib: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }, {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    }>;
+    dataPath: z.ZodEffects<z.ZodString, string, string>;
+    writablePaths: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+}>, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    testEnv: Record<string, string>;
+    image: string;
+    port: number;
+    serviceEnv: Record<string, string>;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    writablePaths: string[];
+}, {
+    name: string;
+    resources: {
+        cpuMillicores: number;
+        memoryMib: number;
+        diskMib: number;
+    };
+    version: string;
+    image: string;
+    port: number;
+    readiness: {
+        command: string[];
+        periodSeconds: number;
+        timeoutSeconds: number;
+        failureThreshold: number;
+    };
+    dataPath: string;
+    testEnv?: Record<string, string> | undefined;
+    serviceEnv?: Record<string, string> | undefined;
+    writablePaths?: string[] | undefined;
+}>, "many">;
+/** The columns of a CodingService row the definition is read from. */
+export interface CodingServiceRow {
+    name: string;
+    version: string;
+    kind: string;
+    image: string;
+    port: number;
+    serviceEnv: unknown;
+    testEnv: unknown;
+    readiness: unknown;
+    resources: unknown;
+    dataPath: string;
+    writablePaths: unknown;
+}
+/** A row as its definition. Throws when the row was edited out of shape (the operator log keeps the name). */
+export declare function catalogEntryFromRow(row: CodingServiceRow): CodingServiceDefinition;
+/** The per-run snapshot of an entry. */
+export declare function resolvedFromDefinition(definition: CodingServiceDefinition): ResolvedCodingService;
+/** CodingRun.services, parsed; a run from before services existed has []. Throws on anything else. */
+export declare function parseStoredServices(value: unknown): ResolvedCodingService[];
+/** The service names in CodingRun.services, read leniently: for wording only, never for launching. */
+export declare function storedServiceNames(value: unknown): string[];
+/** "postgres 16" for each service in CodingRun.services with a valid name and version, for get_run. */
+export declare function storedServiceLabels(value: unknown): string[];
+/** CodingAgentProfile.services: the catalog names this agent's runs may start (any version the catalog has). */
+export declare const AllowedServiceNamesSchema: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>;
+export declare function parseAllowedServiceNames(value: unknown): string[];
+/** What the worker receives for each service (CodingTaskInput.services): never the image or the service's own environment. */
+export declare function workerServices(services: readonly ResolvedCodingService[]): Array<{
+    name: string;
+    version: string;
+    testEnv: Record<string, string>;
+}>;

package/dist/coding/services/catalog.js

@@ -0,0 +1,159 @@
+/**
+ * The coding-run service catalog (docs/coding-services.md): what a repository's
+ * .wardby/services.yaml may name. An entry is admin-managed, trusted data: a
+ * digest-pinned image, the environment it starts with, the variables it hands
+ * the agent's shells, how to tell it is ready, and what it may use. Repository
+ * content only ever names an entry; it never supplies any of these.
+ */
+import { z } from "zod";
+import { isRepositoryDigest } from "../../providers/jobs/docker-isolation.js";
+import { byteLength, CODING_SERVICE_NAME, CODING_SERVICE_VERSION, CodingServiceTestEnvSchema, INVALID_SINGLE_LINE_CONTROL, MAX_CODING_SERVICES, } from "../protocol.js";
+/** "sidecar": a fresh instance in each run's pod. "external" is reserved for shared services reached through the proxy. */
+export const CODING_SERVICE_KINDS = ["sidecar"];
+/** How many service names one agent may be allowed. */
+export const MAX_AGENT_SERVICES = 16;
+export const MAX_SERVICE_ENV = 32;
+const MAX_WRITABLE_PATHS = 4;
+const MAX_PATH_BYTES = 255;
+const SERVICE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const ABSOLUTE_PATH = /^\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+const FORBIDDEN_ROOTS = ["/proc", "/sys", "/dev"];
+const singleLine = (max) => z
+    .string()
+    .refine((value) => byteLength(value) <= max && !INVALID_SINGLE_LINE_CONTROL.test(value), `must be one line of at most ${max} bytes`);
+export const codingServiceNameSchema = z
+    .string()
+    .regex(CODING_SERVICE_NAME, "must be lowercase letters, digits and hyphens, starting with a letter (at most 40)");
+export const codingServiceVersionSchema = z
+    .string()
+    .regex(CODING_SERVICE_VERSION, 'must be a short version such as "16" (letters, digits, ".", "_", "-"; at most 20)');
+const serviceEnvSchema = z.record(z.string(), singleLine(1024)).superRefine((env, ctx) => {
+    const names = Object.keys(env);
+    if (names.length > MAX_SERVICE_ENV) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `must have at most ${MAX_SERVICE_ENV} variables` });
+    }
+    for (const name of names) {
+        if (!SERVICE_ENV_NAME.test(name)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [name], message: "must be a variable name" });
+        }
+    }
+});
+const pathSchema = z
+    .string()
+    .refine((value) => ABSOLUTE_PATH.test(value) &&
+    byteLength(value) <= MAX_PATH_BYTES &&
+    !value.split("/").some((part) => part === "." || part === "..") &&
+    !FORBIDDEN_ROOTS.some((root) => value === root || value.startsWith(`${root}/`)), "must be an absolute path outside /proc, /sys and /dev, without . or .. components");
+export const CodingServiceReadinessSchema = z
+    .object({
+    command: z
+        .array(singleLine(256).refine((value) => value.length > 0, "must not be empty"))
+        .min(1)
+        .max(16),
+    periodSeconds: z.number().int().min(1).max(60),
+    timeoutSeconds: z.number().int().min(1).max(60),
+    failureThreshold: z.number().int().min(1).max(120),
+})
+    .strict();
+export const CodingServiceResourcesSchema = z
+    .object({
+    cpuMillicores: z.number().int().min(100).max(4000),
+    memoryMib: z.number().int().min(64).max(16_384),
+    diskMib: z.number().int().min(64).max(8192),
+})
+    .strict();
+const serviceFields = {
+    name: codingServiceNameSchema,
+    version: codingServiceVersionSchema,
+    image: z.string().max(512).refine(isRepositoryDigest, "must be a registry digest (repo@sha256:<64 hex>)"),
+    port: z.number().int().min(1).max(65_535),
+    serviceEnv: serviceEnvSchema.default({}),
+    testEnv: CodingServiceTestEnvSchema.default({}),
+    readiness: CodingServiceReadinessSchema,
+    resources: CodingServiceResourcesSchema,
+    dataPath: pathSchema,
+    writablePaths: z.array(pathSchema).max(MAX_WRITABLE_PATHS).default([]),
+};
+/** Every mount is its own emptyDir, so no two may be the same directory or nest. */
+function checkMounts(value, ctx) {
+    const paths = [value.dataPath, ...value.writablePaths];
+    for (const [index, a] of paths.entries()) {
+        for (const b of paths.slice(index + 1)) {
+            if (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["writablePaths"], message: `${a} and ${b} overlap` });
+            }
+        }
+    }
+}
+/** One run's snapshot of an entry: what dispatch stores on CodingRun.services and the launcher reads. */
+export const ResolvedCodingServiceSchema = z.object(serviceFields).strict().superRefine(checkMounts);
+/** A catalog entry, as create_service takes it and the CodingService table holds it. */
+export const CodingServiceDefinitionSchema = z
+    .object({ ...serviceFields, kind: z.enum(CODING_SERVICE_KINDS).default("sidecar") })
+    .strict()
+    .superRefine(checkMounts);
+export const StoredCodingServicesSchema = z.array(ResolvedCodingServiceSchema).max(MAX_CODING_SERVICES);
+/** A row as its definition. Throws when the row was edited out of shape (the operator log keeps the name). */
+export function catalogEntryFromRow(row) {
+    const parsed = CodingServiceDefinitionSchema.safeParse({
+        name: row.name,
+        version: row.version,
+        kind: row.kind,
+        image: row.image,
+        port: row.port,
+        serviceEnv: row.serviceEnv,
+        testEnv: row.testEnv,
+        readiness: row.readiness,
+        resources: row.resources,
+        dataPath: row.dataPath,
+        writablePaths: row.writablePaths,
+    });
+    if (!parsed.success)
+        throw new Error(`coding_service_catalog_invalid:${row.name} ${row.version}`);
+    return parsed.data;
+}
+/** The per-run snapshot of an entry. */
+export function resolvedFromDefinition(definition) {
+    const { kind: _kind, ...service } = definition;
+    return service;
+}
+/** CodingRun.services, parsed; a run from before services existed has []. Throws on anything else. */
+export function parseStoredServices(value) {
+    if (value === null || value === undefined)
+        return [];
+    return StoredCodingServicesSchema.parse(value);
+}
+function storedEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const record = entry && typeof entry === "object" ? entry : undefined;
+        return typeof record?.name === "string" && CODING_SERVICE_NAME.test(record.name)
+            ? [{ name: record.name, version: record.version }]
+            : [];
+    });
+}
+/** The service names in CodingRun.services, read leniently: for wording only, never for launching. */
+export function storedServiceNames(value) {
+    return storedEntries(value).map((entry) => entry.name);
+}
+/** "postgres 16" for each service in CodingRun.services with a valid name and version, for get_run. */
+export function storedServiceLabels(value) {
+    return storedEntries(value).flatMap((entry) => typeof entry.version === "string" && CODING_SERVICE_VERSION.test(entry.version)
+        ? [`${entry.name} ${entry.version}`]
+        : []);
+}
+/** CodingAgentProfile.services: the catalog names this agent's runs may start (any version the catalog has). */
+export const AllowedServiceNamesSchema = z
+    .array(codingServiceNameSchema)
+    .max(MAX_AGENT_SERVICES)
+    .transform((names) => [...new Set(names)]);
+export function parseAllowedServiceNames(value) {
+    if (value === null || value === undefined)
+        return [];
+    return AllowedServiceNamesSchema.parse(value);
+}
+/** What the worker receives for each service (CodingTaskInput.services): never the image or the service's own environment. */
+export function workerServices(services) {
+    return services.map(({ name, version, testEnv }) => ({ name, version, testEnv }));
+}

package/dist/coding/services/declaration.d.ts

@@ -0,0 +1,11 @@
+export declare const SERVICE_DECLARATION_PATH = ".wardby/services.yaml";
+export declare const MAX_SERVICE_DECLARATION_BYTES: number;
+export interface DeclaredService {
+    name: string;
+    version: string;
+}
+export declare class ServiceDeclarationError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function parseServiceDeclaration(text: string): DeclaredService[];