@cat-factory/kernel 0.308.0 → 0.310.0

package/dist/ports/runner-transport.d.ts

@@ -1,7 +1,8 @@
 import type { CloudProvider, InstanceSize, StepSubtasks } from '../domain/types.js';
 import type { HarnessFailureCause } from '../domain/harness-failure.js';
 import type { LlmToolSpan } from './llm-trace-sink.js';
-import type { AgentEffortReport } from '@cat-factory/contracts';
+import type { AgentEffortReport, PlatformImageVariant } from '@cat-factory/contracts';
+import { isImageVariantName, isPlatformImageVariant, PLATFORM_IMAGE_VARIANTS } from '@cat-factory/contracts';
 /** Live subtask counts a running job reports (from the coding tool's todo list). */
 export type RunnerJobProgress = StepSubtasks;
 /**
@@ -248,42 +249,61 @@ interface RunnerInfraSetup {
  */
 export type RunnerDispatchKind = 'agent' | 'deploy';
 /**
- * Which executor image a job runs on. `default` is the standard harness image; `ui` is the
- * heavier UI-tester image that bundles Playwright + a browser (the `tester-ui` kind needs it,
- * and only it, so the browser never bloats every other kind's cold-start); `deploy` is the
- * separate deploy-harness image (slim base + `kubectl`/`kustomize`/`helm`).
+ * Which executor image a job runs on, by NAME.
+ *
+ * Three names are the PLATFORM's, because it publishes those images ({@link
+ * PLATFORM_IMAGE_VARIANTS}): `default` is the standard harness image; `ui` is the heavier
+ * UI-tester image that bundles Playwright + a browser (the `tester-ui` kind needs it, and only
+ * it, so the browser never bloats every other kind's cold-start); `deploy` is the separate
+ * deploy-harness image (slim base + `kubectl`/`kustomize`/`helm`).
+ *
+ * Anything else is a DEPLOYMENT's own variant: a slug one of its agent kinds declares
+ * (`AgentStepSpec.image`) and its runner backend maps to an image. That is the whole reason the
+ * type is open rather than a union of the three. The split exists because different kinds need
+ * different images, and a deployment whose own agent needs a tool the harness image has no
+ * reason to carry had two options: install it inside every run, or put it in every kind's cold
+ * start. The platform cannot enumerate those names, and it does not have to: what it owns is the
+ * ROUTING (a variant is part of the container's identity, {@link containerKeyForRef}) and the
+ * REFUSAL below.
  *
  * A backend that cannot serve a declared variant REFUSES the dispatch rather than running the
  * job on its default image. The two are not interchangeable in the direction that matters: a
  * browser-driven tester on the plain image has no browser, and it discovers that only after a
  * checkout, an install and a model's first turns have been paid for, then reports an `abort`
- * indistinguishable from an app that would not boot. Naming the missing wiring at dispatch
- * costs nothing and says which knob to set.
+ * indistinguishable from an app that would not boot. A deployment's own variant is worse still,
+ * because nothing in the platform knows what it carried, so the job would report a missing
+ * artifact with no cause anywhere. Naming the missing wiring at dispatch costs nothing and says
+ * which knob to set.
  */
-export type RunnerImageVariant = 'default' | 'ui' | 'deploy';
+export type RunnerImageVariant = string;
+export { PLATFORM_IMAGE_VARIANTS, isPlatformImageVariant, isImageVariantName };
+export type { PlatformImageVariant };
 /**
- * The {@link RunnerImageVariant} vocabulary as DATA, so a reader can narrow a string against it
- * rather than cast. Kept beside the type it enumerates and typed as the member list, so adding a
- * variant to the union without adding it here fails to compile.
+ * The `default:` arm of a backend's exhaustive switch over {@link PlatformImageVariant}: it takes
+ * `never`, so publishing a fourth platform image fails the BUILD in every backend until each
+ * decides what to do with it, and it still refuses honestly at RUN time for the case the type
+ * cannot see, a value an older job body or a stored step still carries after this build retired it.
+ *
+ * The compile-time half is the load-bearing one, because the alternative is silent in the worst
+ * direction: a backend that fell through would run the job on its default image, and nothing
+ * downstream can say what the variant was supposed to carry. The DEPLOYMENT-owned half of the
+ * vocabulary is open and gets {@link deploymentImageVariantMessage} instead; this arm is only ever
+ * reached by a name the platform itself claimed.
  */
-export declare const RUNNER_IMAGE_VARIANTS: readonly RunnerImageVariant[];
-/** Whether a string names a variant THIS build can serve. */
-export declare function isRunnerImageVariant(value: string | null | undefined): value is RunnerImageVariant;
+export declare function unservablePlatformImageVariant(variant: never): never;
 /**
- * The `details.reason` every backend carries on the `UnavailableError` it raises for a
- * declared image variant it cannot serve. ONE constant because it is a machine-readable wire
- * vocabulary the SPA and the run record branch on, and each backend refuses in its own file: as
- * a per-file string literal a typo in one produces a reason nothing recognises and no typecheck
- * fails.
+ * The refusal a DEPLOYMENT-named image variant earns when the resolved runner backend maps it to
+ * nothing, with the per-backend knob named by the caller.
+ *
+ * One message, in kernel, because three backends refuse it and an operator reading three
+ * wordings for one misconfiguration learns three things instead of one. The platform's own
+ * variants keep their bespoke messages: the platform knows what `ui` is FOR, so it can say what
+ * a deployment loses by leaving it unwired and what to do instead, and this one cannot say
+ * anything about a variant it has never heard of beyond where the mapping goes.
  */
+export declare function deploymentImageVariantMessage(variant: string, setting: string): string;
+/** The `details.reason` every unwired-image refusal carries, whoever raises it. */
 export declare const RUNNER_IMAGE_UNWIRED_REASON = "runner_image_unwired";
-/**
- * The `default:` arm of a backend's exhaustive switch over {@link RunnerImageVariant}: it takes
- * `never`, so adding a member to the union fails the BUILD until that backend decides what to do
- * with it, and it still refuses honestly at RUN time for the case the type cannot see — a value
- * this build retired that an older row or an older job body still carries.
- */
-export declare function unservableImageVariant(variant: never): never;
 /**
  * Optional, transport-level provisioning hints resolved per-service at dispatch.
  * A self-hosted pool forwards `instanceTypeId` (and `provider`) so it can provision
@@ -613,13 +633,27 @@ export declare function containerKeyForRef(ref: RunnerJobRef): string;
 /**
  * The parts a container key encodes, the exact inverse of {@link containerKeyForRef}.
  *
- * The prefix is stripped ONLY when it names a variant this build knows. A bare
- * "everything before the first colon is a variant" split is lossy in the direction that
- * destroys data: a key carrying a colon for any OTHER reason (a job-id scheme, an
- * operator-created label) would be truncated to a run id that matches no run, and the orphan
- * sweep below then kills a live container for being unrecognised — the very misread this
- * inverse exists to prevent. An unrecognised prefix therefore answers "the whole key is the
- * run id", which at worst leaves a container for the next sweep.
+ * The prefix is stripped ONLY when it is SHAPED like a variant name. A bare "everything before
+ * the first colon is a variant" split is lossy in the direction that destroys data: a key
+ * carrying a colon for any OTHER reason (a job-id scheme, an operator-created label) would be
+ * truncated to a run id that matches no run, and the orphan sweep below then kills a live
+ * container for being unrecognised, the very misread this inverse exists to prevent. A prefix
+ * that is not variant-shaped therefore answers "the whole key is the run id", which at worst
+ * leaves a container for the next sweep.
+ *
+ * SHAPE rather than membership, because variant names are open: a deployment's own is a slug
+ * only its runner backend can map, and this function is read by a reaper that holds no backend
+ * config. The rule is the one every declaring boundary already enforces (`checkAgentImageVariants`
+ * at boot, the backends' variant-map schemas), so a prefix this rejects is one no registration
+ * could have produced.
+ *
+ * What that leaves is a prefix which IS slug-shaped and was never a variant. Open names make that
+ * case unknowable HERE, so it is not decided here: {@link containerKeyForRef} refuses to mint a key
+ * this function would read back differently, which is what makes the pair exact rather than merely
+ * careful. Every key the inventory holds was written by that producer, so a prefix reaching this
+ * point and passing the shape test came from a variant a registration declared. The split of
+ * responsibility is the point: the reader refuses anything UNSHAPED, and the writer refuses
+ * anything AMBIGUOUS, because only one of them holds the ref to compare against.
  */
 export declare function parseContainerKey(containerKey: string): {
     runId: string;
@@ -722,5 +756,4 @@ export interface RunnerTransport {
      */
     stopJob?(ref: RunnerJobRef): Promise<RunnerJobStopOutcome>;
 }
-export {};
 //# sourceMappingURL=runner-transport.d.ts.map

package/dist/ports/runner-transport.d.ts.map

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

package/dist/ports/runner-transport.js

@@ -1,4 +1,5 @@
-import { UnavailableError } from '../domain/errors.js';
+import { isImageVariantName, isPlatformImageVariant, PLATFORM_IMAGE_VARIANTS, } from '@cat-factory/contracts';
+import { UnavailableError, ValidationError } from '../domain/errors.js';
 /**
  * The one-line `error` a transport reports beside `evicted` when the job's container/runner is
  * simply GONE — the poll found no such job. Owned here rather than copied per transport because
@@ -23,35 +24,46 @@ export const CONTAINER_EVICTION_ERROR = 'Job not found (container evicted or cra
  * killed its container each time and reported infrastructure churn.
  */
 export const HARNESS_SHUTDOWN_ERROR = 'The executor-harness shut down while this job was still running';
+// The reserved-name half of the vocabulary lives on the WIRE (`@cat-factory/contracts`), because
+// a runner backend's variant map is edited in the SPA and an agent kind's declaration is written
+// by a deployment: both must be held to one list of names the platform has already claimed.
+export { PLATFORM_IMAGE_VARIANTS, isPlatformImageVariant, isImageVariantName };
 /**
- * The {@link RunnerImageVariant} vocabulary as DATA, so a reader can narrow a string against it
- * rather than cast. Kept beside the type it enumerates and typed as the member list, so adding a
- * variant to the union without adding it here fails to compile.
+ * The `default:` arm of a backend's exhaustive switch over {@link PlatformImageVariant}: it takes
+ * `never`, so publishing a fourth platform image fails the BUILD in every backend until each
+ * decides what to do with it, and it still refuses honestly at RUN time for the case the type
+ * cannot see, a value an older job body or a stored step still carries after this build retired it.
+ *
+ * The compile-time half is the load-bearing one, because the alternative is silent in the worst
+ * direction: a backend that fell through would run the job on its default image, and nothing
+ * downstream can say what the variant was supposed to carry. The DEPLOYMENT-owned half of the
+ * vocabulary is open and gets {@link deploymentImageVariantMessage} instead; this arm is only ever
+ * reached by a name the platform itself claimed.
  */
-export const RUNNER_IMAGE_VARIANTS = ['default', 'ui', 'deploy'];
-/** Whether a string names a variant THIS build can serve. */
-export function isRunnerImageVariant(value) {
-    return value != null && RUNNER_IMAGE_VARIANTS.includes(value);
+export function unservablePlatformImageVariant(variant) {
+    throw new UnavailableError(`This step declared the '${String(variant)}' executor image, which this backend does not ` +
+        'serve. It is a platform image this build does not know: re-pick the executor image on the ' +
+        "agent kind's registration.", RUNNER_IMAGE_UNWIRED_REASON, { image: String(variant) });
 }
 /**
- * The `details.reason` every backend carries on the `UnavailableError` it raises for a
- * declared image variant it cannot serve. ONE constant because it is a machine-readable wire
- * vocabulary the SPA and the run record branch on, and each backend refuses in its own file: as
- * a per-file string literal a typo in one produces a reason nothing recognises and no typecheck
- * fails.
- */
-export const RUNNER_IMAGE_UNWIRED_REASON = 'runner_image_unwired';
-/**
- * The `default:` arm of a backend's exhaustive switch over {@link RunnerImageVariant}: it takes
- * `never`, so adding a member to the union fails the BUILD until that backend decides what to do
- * with it, and it still refuses honestly at RUN time for the case the type cannot see — a value
- * this build retired that an older row or an older job body still carries.
+ * The refusal a DEPLOYMENT-named image variant earns when the resolved runner backend maps it to
+ * nothing, with the per-backend knob named by the caller.
+ *
+ * One message, in kernel, because three backends refuse it and an operator reading three
+ * wordings for one misconfiguration learns three things instead of one. The platform's own
+ * variants keep their bespoke messages: the platform knows what `ui` is FOR, so it can say what
+ * a deployment loses by leaving it unwired and what to do instead, and this one cannot say
+ * anything about a variant it has never heard of beyond where the mapping goes.
  */
-export function unservableImageVariant(variant) {
-    throw new UnavailableError(`This step declared the '${String(variant)}' executor image, which this backend does not ` +
-        'serve. It is not a variant this build knows: re-pick the executor image on the agent ' +
-        "kind's registration.", RUNNER_IMAGE_UNWIRED_REASON, { image: String(variant) });
+export function deploymentImageVariantMessage(variant, setting) {
+    return (`This step's agent kind declares the "${variant}" executor image, which this deployment's ` +
+        `runner backend maps to no image. Add "${variant}" to ${setting}, or drop the kind's ` +
+        `\`image\` declaration if the default harness image is enough: running the default instead ` +
+        `would produce a job without whatever "${variant}" carries, and a step reporting a missing ` +
+        `result with nothing naming the cause.`);
 }
+/** The `details.reason` every unwired-image refusal carries, whoever raises it. */
+export const RUNNER_IMAGE_UNWIRED_REASON = 'runner_image_unwired';
 /**
  * The container identity a ref addresses on a per-run container backend: the run id for the
  * default image, qualified by the variant for anything else.
@@ -62,18 +74,58 @@ export function unservableImageVariant(variant) {
  * a reap from a cron all land on the same container with nothing passed between them.
  */
 export function containerKeyForRef(ref) {
-    return ref.image && ref.image !== 'default' ? `${ref.image}:${ref.runId}` : ref.runId;
+    const key = ref.image && ref.image !== 'default' ? `${ref.image}:${ref.runId}` : ref.runId;
+    // The two must be EXACT inverses, and the PRODUCER is the only side that can check it:
+    // `parseContainerKey` reads keys with no ref in hand, so it cannot tell a run id that merely
+    // LOOKS variant-qualified from one that is (see its own doc for why the test it makes is a shape
+    // and not a lookup). Checking here converts the one input class that would break the inverse into
+    // a refused dispatch that NAMES the cause, instead of a key the reaper later maps to no run and
+    // kills a live container for.
+    //
+    // Unreachable for every run-id scheme the platform mints today (all `[A-Za-z0-9_-]`, which cannot
+    // contain the separator), which is exactly why this is a guard and not an escaping scheme: the
+    // invariant the pair rests on is "a run id carries no `:`", and it was previously assumed rather
+    // than stated anywhere. A future scheme that wants one has to pick a different separator, and this
+    // is where it finds out: at the first dispatch, in one place, rather than as a sweep deleting
+    // containers weeks later.
+    const parsed = parseContainerKey(key);
+    if (parsed.runId !== ref.runId || (parsed.image ?? 'default') !== (ref.image || 'default')) {
+        throw new ValidationError(`Cannot address a container for run "${ref.runId}"${ref.image ? ` on the "${ref.image}" executor image` : ''}: ` +
+            `the container key "${key}" does not read back as the run and image it was built from, so ` +
+            `every reader of it (the dispatch, the poll, the orphan sweep) would disagree about which ` +
+            `run owns the container. A run id may not put a variant-shaped segment before a ":", and a ` +
+            `variant name must be a lower-kebab slug.`, {
+            reason: 'container_key_not_reversible',
+            runId: ref.runId,
+            ...(ref.image ? { image: ref.image } : {}),
+        });
+    }
+    return key;
 }
 /**
  * The parts a container key encodes, the exact inverse of {@link containerKeyForRef}.
  *
- * The prefix is stripped ONLY when it names a variant this build knows. A bare
- * "everything before the first colon is a variant" split is lossy in the direction that
- * destroys data: a key carrying a colon for any OTHER reason (a job-id scheme, an
- * operator-created label) would be truncated to a run id that matches no run, and the orphan
- * sweep below then kills a live container for being unrecognised — the very misread this
- * inverse exists to prevent. An unrecognised prefix therefore answers "the whole key is the
- * run id", which at worst leaves a container for the next sweep.
+ * The prefix is stripped ONLY when it is SHAPED like a variant name. A bare "everything before
+ * the first colon is a variant" split is lossy in the direction that destroys data: a key
+ * carrying a colon for any OTHER reason (a job-id scheme, an operator-created label) would be
+ * truncated to a run id that matches no run, and the orphan sweep below then kills a live
+ * container for being unrecognised, the very misread this inverse exists to prevent. A prefix
+ * that is not variant-shaped therefore answers "the whole key is the run id", which at worst
+ * leaves a container for the next sweep.
+ *
+ * SHAPE rather than membership, because variant names are open: a deployment's own is a slug
+ * only its runner backend can map, and this function is read by a reaper that holds no backend
+ * config. The rule is the one every declaring boundary already enforces (`checkAgentImageVariants`
+ * at boot, the backends' variant-map schemas), so a prefix this rejects is one no registration
+ * could have produced.
+ *
+ * What that leaves is a prefix which IS slug-shaped and was never a variant. Open names make that
+ * case unknowable HERE, so it is not decided here: {@link containerKeyForRef} refuses to mint a key
+ * this function would read back differently, which is what makes the pair exact rather than merely
+ * careful. Every key the inventory holds was written by that producer, so a prefix reaching this
+ * point and passing the shape test came from a variant a registration declared. The split of
+ * responsibility is the point: the reader refuses anything UNSHAPED, and the writer refuses
+ * anything AMBIGUOUS, because only one of them holds the ref to compare against.
  */
 export function parseContainerKey(containerKey) {
     const separator = containerKey.indexOf(':');
@@ -82,7 +134,7 @@ export function parseContainerKey(containerKey) {
     const prefix = containerKey.slice(0, separator);
     // `default` is never a prefix (`containerKeyForRef` emits the bare run id for it), so a key
     // spelling it out is not one this function produced and is left whole.
-    if (prefix === 'default' || !isRunnerImageVariant(prefix))
+    if (prefix === 'default' || !isImageVariantName(prefix))
         return { runId: containerKey };
     return { runId: containerKey.slice(separator + 1), image: prefix };
 }

package/dist/ports/runner-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner-transport.js","sourceRoot":"","sources":["../../src/ports/runner-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AA6CtD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,8CAA8C,CAAA;AAEtF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,iEAAiE,CAAA;AA4NnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAkC,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;AAE/F,6DAA6D;AAC7D,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,OAAO,KAAK,IAAI,IAAI,IAAK,qBAA2C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAc;IACnD,MAAM,IAAI,gBAAgB,CACxB,2BAA2B,MAAM,CAAC,OAAO,CAAC,gDAAgD;QACxF,uFAAuF;QACvF,sBAAsB,EACxB,2BAA2B,EAC3B,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAC3B,CAAA;AACH,CAAC;AAuUD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAiB;IAClD,OAAO,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAA;AACvF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IAIpD,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC3C,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;IAClD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;IAC/C,4FAA4F;IAC5F,uEAAuE;IACvE,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;IACzF,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,iBAAiB,CAAC,YAAY,CAAC,CAAC,KAAK,CAAA;AAC9C,CAAC"}
+{"version":3,"file":"runner-transport.js","sourceRoot":"","sources":["../../src/ports/runner-transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.308.0",
+  "version": "0.310.0",
   "description": "Shared vocabulary, pure logic, and port interfaces for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "ai": "^7.0.64",
     "yaml": "^2.9.0",
-    "@cat-factory/contracts": "0.318.0"
+    "@cat-factory/contracts": "0.320.0"
   },
   "devDependencies": {
     "@stryker-mutator/core": "9.6.1",