@cat-factory/kernel 0.308.0 → 0.309.0

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.309.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.319.0"
   },
   "devDependencies": {
     "@stryker-mutator/core": "9.6.1",