@cat-factory/kernel 0.300.0 → 0.302.0

package/dist/domain/cache-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-policy.d.ts","sourceRoot":"","sources":["../../src/domain/cache-policy.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,WAAW,GAInB,aAAa,GAEb,oBAAoB,GAEpB,MAAM,CAAA;AAEV,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAWjE;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D"}
+{"version":3,"file":"cache-policy.d.ts","sourceRoot":"","sources":["../../src/domain/cache-policy.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,WAAW,GAInB,aAAa,GAEb,oBAAoB,GAEpB,MAAM,CAAA;AAEV,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAejE;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D"}

package/dist/domain/cache-policy.js

@@ -15,6 +15,10 @@ export function providerCachePolicy(provider) {
         case 'openai':
         case 'deepseek':
         case 'qwen':
+        // xAI caches prompt prefixes automatically and bills the hits at its own published
+        // cached-input rate, with no per-request opt-in, so it belongs with the auto-prefix
+        // group rather than Anthropic's explicit `cache_control` breakpoints.
+        case 'xai':
             return 'auto-prefix';
         case 'anthropic':
             return 'explicit-anthropic';

package/dist/domain/cache-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-policy.js","sourceRoot":"","sources":["../../src/domain/cache-policy.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,qFAAqF;AACrF,oFAAoF;AACpF,oFAAoF;AACpF,oFAAoF;AACpF,oFAAoF;AACpF,EAAE;AACF,sFAAsF;AACtF,mFAAmF;AACnF,uFAAuF;AACvF,kFAAkF;AAYlF,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,aAAa,CAAA;QACtB,KAAK,WAAW;YACd,OAAO,oBAAoB,CAAA;QAC7B;YACE,OAAO,MAAM,CAAA;IACjB,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAA;AACjD,CAAC"}
+{"version":3,"file":"cache-policy.js","sourceRoot":"","sources":["../../src/domain/cache-policy.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,qFAAqF;AACrF,oFAAoF;AACpF,oFAAoF;AACpF,oFAAoF;AACpF,oFAAoF;AACpF,EAAE;AACF,sFAAsF;AACtF,mFAAmF;AACnF,uFAAuF;AACvF,kFAAkF;AAYlF,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,MAAM,CAAC;QACZ,mFAAmF;QACnF,oFAAoF;QACpF,sEAAsE;QACtE,KAAK,KAAK;YACR,OAAO,aAAa,CAAA;QACtB,KAAK,WAAW;YACd,OAAO,oBAAoB,CAAA;QAC7B;YACE,OAAO,MAAM,CAAA;IACjB,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAA;AACjD,CAAC"}

package/dist/domain/environment-failure.d.ts

@@ -0,0 +1,77 @@
+import type { EnvironmentFailureReason } from './types.js';
+import { UnavailableError } from './errors.js';
+/**
+ * A provisioning failure carrying its machine-readable cause.
+ *
+ * `UnavailableError` for every class, including the manifest one, because `code` is the STATUS
+ * CLASS and the answer is uniformly "this environment could not be stood up"; the cause that
+ * differs is `details.reason`. That is the split the domain-error vocabulary asks for, and it is
+ * why there is no per-cause error class to choose between.
+ *
+ * An unclassified failure carries NO reason rather than a null one, so no reader can mistake
+ * "this was not classified" for a classification. That distinction is load-bearing: unclassified
+ * is not repo-fixable, and a provider that has not adopted this must never be read as having
+ * asserted something about its failures.
+ */
+export declare function environmentFailure(message: string, reason: EnvironmentFailureReason | null | undefined): UnavailableError;
+/**
+ * A `{{placeholder}}` a provider's templated inputs reference but cannot fill.
+ *
+ * Every built-in provider renders its manifests/compose files through the same lenient
+ * substitution, where an unknown key resolves to the empty string. That leniency is deliberate (a
+ * template may carry an optional value) and it is also how a correct file becomes an invalid one:
+ * `image: "{{image}}"` renders to `image: ""`, and the platform it is submitted to then reports a
+ * required field missing on a document whose source says nothing of the kind.
+ */
+export interface UnresolvedPlaceholder {
+    /** The placeholder key as written, without braces. */
+    key: string;
+    /**
+     * The connection/handler field an operator sets to supply it, for a key the PLATFORM derives
+     * from configuration rather than from the run. Absent for a key nothing known fills, which is a
+     * template referencing something that was never going to exist and reads differently to whoever
+     * has to fix it.
+     */
+    configField?: string;
+}
+/**
+ * The placeholders `text` references that `vars` cannot fill, deduplicated and in order of first
+ * appearance.
+ *
+ * Scans the SOURCE, before substitution, because afterwards the evidence is gone: an empty string
+ * in a rendered file is indistinguishable from an empty string its author wrote. A key that is
+ * PRESENT but empty counts as unresolved too, since an operator who set the supplying field to a
+ * blank string has supplied nothing and the file breaks identically.
+ *
+ * `configFields` maps a placeholder key to the setting that supplies it, and is the provider's to
+ * pass because only the provider knows its own configuration shape (Kubernetes fills `{{image}}`
+ * from `imageTemplate`; another backend may fill it from something else, or not at all). Keys the
+ * RUN supplies (`blockId`, `branch`, `pullNumber`, …) are deliberately left out of that map: one
+ * of those rendering empty is a fact about the run, and naming a config field for it would send an
+ * operator to a setting that would not have helped.
+ */
+export declare function unresolvedPlaceholders(text: string, vars: Record<string, string>, configFields?: Record<string, string>): UnresolvedPlaceholder[];
+/**
+ * The operator-facing refusal for a template the deployment's own CONFIGURATION cannot fill, or
+ * `null` when there is nothing an operator could set.
+ *
+ * Refusing BEFORE submitting is the whole point, and providers should call this rather than
+ * rendering empties and letting the platform reject them. The rejection that comes back describes
+ * the RESULT and blames the file, which is how a correct `image: "{{image}}"` was reported as a
+ * Deployment missing a required image. This names the placeholder, names the field that fills it,
+ * and says the repository is not at fault, none of which the platform being deployed to could
+ * ever have told anyone.
+ *
+ * SCOPED to the keys carrying a `configField`, and that scope is the refusal's whole justification
+ * rather than a detail of it. A config-backed key is unambiguous: the platform undertook to supply
+ * the value, the deployment has not been told how, and the message can name the setting to change.
+ * Everything else unresolved is a key the RUN supplies, where absent and empty are the same value
+ * and opposite facts: `frontendOrigins` is absent for a service no frontend binds, `peerEnvUrls`
+ * for the first frame of a fan-out, `branch` and `pullNumber` for a peer frame that carries no PR
+ * context. Each renders empty on purpose, so a template that folds one into a CORS list or a label
+ * is CORRECT and refusing it would fail a provision naming no setting anyone could fix. The
+ * lenient substitution stays the documented behaviour there; only the class an operator can act on
+ * is worth stopping a deployment for.
+ */
+export declare function describeUnfilledConfigPlaceholders(missing: UnresolvedPlaceholder[]): string | null;
+//# sourceMappingURL=environment-failure.d.ts.map

package/dist/domain/environment-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-failure.d.ts","sourceRoot":"","sources":["../../src/domain/environment-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AA4B9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,GAClD,gBAAgB,CAElB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAA;IACX;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACxC,qBAAqB,EAAE,CAYzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,qBAAqB,EAAE,GAC/B,MAAM,GAAG,IAAI,CAaf"}

package/dist/domain/environment-failure.js

@@ -0,0 +1,106 @@
+import { UnavailableError } from './errors.js';
+// ---------------------------------------------------------------------------
+// The PROVIDER-NEUTRAL half of environment-failure classification: what any environment
+// provider — the built-in Kubernetes / compose / Cloudflare backends, and equally a backend a
+// deployment registers into `EnvironmentBackendRegistry` — uses to say WHY a provision failed in
+// a way the engine can act on.
+//
+// It lives in kernel rather than beside the Kubernetes provider precisely because a custom
+// backend must be able to participate. The engine's remediation decision ("may an automated fixer
+// be dispatched at this failure?") is keyed off `EnvironmentFailureReason`, so a provider that
+// cannot state a reason gets the safe answer (never fixable) and is silently excluded from the
+// mechanism. Giving it the same helpers the built-ins use is what makes the classification an
+// extension point instead of a Kubernetes-only feature.
+//
+// A custom provider participates by doing one of two things, both optional and both degrading
+// safely, and WHICH one is decided by how it reports the failure rather than by preference:
+//   1. a provider that THROWS raises {@link environmentFailure} (or any `DomainError` carrying
+//      `details.reason`) instead of a bare `Error`, so the engine reads the class off the error
+//      rather than out of the prose;
+//   2. a provider that instead returns `status: 'failed'` (a deterministic rejection it did not
+//      consider exceptional, and the shape every container-backed provision settles into) has no
+//      error to carry a reason, so it states one on `ProvisionedEnvironment.reason`. The engine
+//      threads that alongside the handle to the same decision the thrown reason reaches.
+// A provider that does neither behaves exactly as every provider did before this existed: its
+// failures are unclassified, and unclassified is never repo-fixable.
+// ---------------------------------------------------------------------------
+/**
+ * A provisioning failure carrying its machine-readable cause.
+ *
+ * `UnavailableError` for every class, including the manifest one, because `code` is the STATUS
+ * CLASS and the answer is uniformly "this environment could not be stood up"; the cause that
+ * differs is `details.reason`. That is the split the domain-error vocabulary asks for, and it is
+ * why there is no per-cause error class to choose between.
+ *
+ * An unclassified failure carries NO reason rather than a null one, so no reader can mistake
+ * "this was not classified" for a classification. That distinction is load-bearing: unclassified
+ * is not repo-fixable, and a provider that has not adopted this must never be read as having
+ * asserted something about its failures.
+ */
+export function environmentFailure(message, reason) {
+    return new UnavailableError(message, reason ?? undefined);
+}
+/**
+ * The placeholders `text` references that `vars` cannot fill, deduplicated and in order of first
+ * appearance.
+ *
+ * Scans the SOURCE, before substitution, because afterwards the evidence is gone: an empty string
+ * in a rendered file is indistinguishable from an empty string its author wrote. A key that is
+ * PRESENT but empty counts as unresolved too, since an operator who set the supplying field to a
+ * blank string has supplied nothing and the file breaks identically.
+ *
+ * `configFields` maps a placeholder key to the setting that supplies it, and is the provider's to
+ * pass because only the provider knows its own configuration shape (Kubernetes fills `{{image}}`
+ * from `imageTemplate`; another backend may fill it from something else, or not at all). Keys the
+ * RUN supplies (`blockId`, `branch`, `pullNumber`, …) are deliberately left out of that map: one
+ * of those rendering empty is a fact about the run, and naming a config field for it would send an
+ * operator to a setting that would not have helped.
+ */
+export function unresolvedPlaceholders(text, vars, configFields = {}) {
+    const found = new Map();
+    // The same pattern the providers substitute with, so the two cannot disagree about what counts
+    // as a placeholder.
+    for (const match of text.matchAll(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g)) {
+        const key = match[1];
+        if (found.has(key))
+            continue;
+        if ((vars[key] ?? '') !== '')
+            continue;
+        const configField = configFields[key];
+        found.set(key, { key, ...(configField ? { configField } : {}) });
+    }
+    return [...found.values()];
+}
+/**
+ * The operator-facing refusal for a template the deployment's own CONFIGURATION cannot fill, or
+ * `null` when there is nothing an operator could set.
+ *
+ * Refusing BEFORE submitting is the whole point, and providers should call this rather than
+ * rendering empties and letting the platform reject them. The rejection that comes back describes
+ * the RESULT and blames the file, which is how a correct `image: "{{image}}"` was reported as a
+ * Deployment missing a required image. This names the placeholder, names the field that fills it,
+ * and says the repository is not at fault, none of which the platform being deployed to could
+ * ever have told anyone.
+ *
+ * SCOPED to the keys carrying a `configField`, and that scope is the refusal's whole justification
+ * rather than a detail of it. A config-backed key is unambiguous: the platform undertook to supply
+ * the value, the deployment has not been told how, and the message can name the setting to change.
+ * Everything else unresolved is a key the RUN supplies, where absent and empty are the same value
+ * and opposite facts: `frontendOrigins` is absent for a service no frontend binds, `peerEnvUrls`
+ * for the first frame of a fan-out, `branch` and `pullNumber` for a peer frame that carries no PR
+ * context. Each renders empty on purpose, so a template that folds one into a CORS list or a label
+ * is CORRECT and refusing it would fail a provision naming no setting anyone could fix. The
+ * lenient substitution stays the documented behaviour there; only the class an operator can act on
+ * is worth stopping a deployment for.
+ */
+export function describeUnfilledConfigPlaceholders(missing) {
+    const blocking = missing.filter((m) => m.configField);
+    if (blocking.length === 0)
+        return null;
+    const items = blocking.map((m) => `'{{${m.key}}}' (supplied by this environment connection's '${m.configField}' setting, which is not set)`);
+    return (`The deployment files could not be rendered: ${items.join('; ')}. ` +
+        'The repository is not at fault here and editing these files is the wrong fix: the ' +
+        'placeholder exists so the value can vary per environment, and hard-coding it would defeat ' +
+        'that. Set the missing configuration on the environment connection and retry.');
+}
+//# sourceMappingURL=environment-failure.js.map

package/dist/domain/environment-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-failure.js","sourceRoot":"","sources":["../../src/domain/environment-failure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C,8EAA8E;AAC9E,wFAAwF;AACxF,8FAA8F;AAC9F,iGAAiG;AACjG,+BAA+B;AAC/B,EAAE;AACF,2FAA2F;AAC3F,kGAAkG;AAClG,+FAA+F;AAC/F,+FAA+F;AAC/F,8FAA8F;AAC9F,wDAAwD;AACxD,EAAE;AACF,8FAA8F;AAC9F,4FAA4F;AAC5F,+FAA+F;AAC/F,gGAAgG;AAChG,qCAAqC;AACrC,gGAAgG;AAChG,iGAAiG;AACjG,gGAAgG;AAChG,yFAAyF;AACzF,8FAA8F;AAC9F,qEAAqE;AACrE,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,MAAmD;IAEnD,OAAO,IAAI,gBAAgB,CAAC,OAAO,EAAE,MAAM,IAAI,SAAS,CAAC,CAAA;AAC3D,CAAC;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,IAA4B,EAC5B,YAAY,GAA2B,EAAE;IAEzC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiC,CAAA;IACtD,+FAA+F;IAC/F,oBAAoB;IACpB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,iCAAiC,CAAC,EAAE,CAAC;QACrE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAA;QACrB,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE;YAAE,SAAQ;QACtC,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;QACrC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,kCAAkC,CAChD,OAAgC;IAEhC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CACxB,CAAC,CAAC,EAAE,EAAE,CACJ,MAAM,CAAC,CAAC,GAAG,mDAAmD,CAAC,CAAC,WAAW,8BAA8B,CAC5G,CAAA;IACD,OAAO,CACL,+CAA+C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACnE,oFAAoF;QACpF,4FAA4F;QAC5F,8EAA8E,CAC/E,CAAA;AACH,CAAC"}

package/dist/domain/model-catalog.d.ts

@@ -0,0 +1,3 @@
+import type { SelectableModel } from './models.js';
+export declare const MODEL_CATALOG: SelectableModel[];
+//# sourceMappingURL=model-catalog.d.ts.map

package/dist/domain/model-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-catalog.d.ts","sourceRoot":"","sources":["../../src/domain/model-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAiClD,eAAO,MAAM,aAAa,EAAE,eAAe,EAkkB1C,CAAA"}