typekro 0.33.10 → 0.34.0

package/dist/factories/gateway-api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/factories/gateway-api/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAiBH,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACtD;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,EAAE,CAAC;IACJ,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;KACtD,EAAE,CAAC;CACL;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;QACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;KACtD,EAAE,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;KACtD,EAAE,CAAC;CACL;AASD,iFAAiF;AACjF,eAAO,MAAM,2BAA2B;;;;;MAKtC,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,OAAO,2BAA2B,CAAC,KAAK,CAAC;AA2D7E,2BAA2B;AAC3B,eAAO,MAAM,sBAAsB;;;;;;;;;MAIjC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CACtE,OAAO,sBAAsB,CAAC,KAAK,EACnC,gBAAgB,CACjB,GAAG;IAAE,cAAc,EAAE,WAAW,CAAA;CAAE,CAAC;AAMpC,uDAAuD;AACvD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;MAS9B,CAAC;AAEH,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC;AAE7D,sCAAsC;AACtC,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;MAWjC,CAAC;AAEH,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GAAG,OAAO,sBAAsB,CAAC,KAAK,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAOhC,CAAC;AAEH,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,OAAO,qBAAqB,CAAC,KAAK,CAAC;AAQjE,sBAAsB;AACtB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiB5B,CAAC;AAEH,sBAAsB;AACtB,MAAM,MAAM,WAAW,GAAG,OAAO,iBAAiB,CAAC,KAAK,CAAC;AAMzD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;MAOhC,CAAC;AAEH,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,OAAO,qBAAqB,CAAC,KAAK,CAAC;AAEjE,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB;;;;;;;MAQ3B,CAAC;AAEH,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,OAAO,gBAAgB,CAAC,KAAK,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;MAS/B,CAAC;AAEH,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,CAAC,KAAK,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB;;;;;;;;;;MAIjC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG,OAAO,sBAAsB,CAAC,KAAK,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA8BhC,CAAC;AAEH,oDAAoD;AACpD,MAAM,MAAM,eAAe,GAAG,OAAO,qBAAqB,CAAC,KAAK,CAAC;AAOjE,0CAA0C;AAC1C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiB9B,CAAC;AAEH,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAI9B,CAAC;AAEH,wBAAwB;AACxB,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC;AAE7D,oDAAoD;AACpD,eAAO,MAAM,oBAAoB;;;;;;;;;;;MAO/B,CAAC;AAEH,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,CAAC,KAAK,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAM9B,CAAC;AAEH,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC;AAE7D,wBAAwB;AACxB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAI9B,CAAC;AAEH,wBAAwB;AACxB,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC;AAM7D;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;MAWnC,CAAC;AAEH,6BAA6B;AAC7B,MAAM,MAAM,kBAAkB,GAAG,OAAO,wBAAwB,CAAC,KAAK,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;MAkBrC,CAAC;AAEH,+BAA+B;AAC/B,MAAM,MAAM,oBAAoB,GAAG,OAAO,0BAA0B,CAAC,KAAK,CAAC;AAc3E;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC;;IAEjD,kDAAkD;;IAElD,4DAA4D;;IAE5D,qEAAqE;;CAE7D,CAAC;AAEX,6EAA6E;AAC7E,eAAO,MAAM,yCAAyC;;;IATpD,kDAAkD;;IAElD,4DAA4D;;IAE5D,qEAAqE;;CAQ7D,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,uCAAuC;;;;;MAA+C,CAAC;AAEpG,2EAA2E;AAC3E,MAAM,MAAM,iCAAiC,GAC3C,OAAO,uCAAuC,CAAC,KAAK,CAAC;AAEvD,uEAAuE;AACvE,eAAO,MAAM,0CAA0C;;;;;;MAEtD,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,oCAAoC,GAC9C,OAAO,0CAA0C,CAAC,KAAK,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MASvC,CAAC;AAEH,4CAA4C;AAC5C,MAAM,MAAM,sBAAsB,GAAG,OAAO,4BAA4B,CAAC,KAAK,CAAC"}

package/dist/factories/gateway-api/types.js

@@ -0,0 +1,417 @@
+/**
+ * Shared upstream Gateway API type definitions.
+ *
+ * Extracted from `src/factories/envoy-ai-gateway` (see #176) so that every
+ * Gateway API implementation in TypeKro — Envoy Gateway, Traefik v3, and any
+ * future controller — describes `GatewayClass`, `Gateway`, `HTTPRoute`,
+ * `GRPCRoute`, `ReferenceGrant` and `BackendTLSPolicy` with one set of types.
+ *
+ * Vendor-specific policy CRDs (`BackendTrafficPolicy`, `AIGatewayRoute`,
+ * Traefik `Middleware`, ...) deliberately stay in their own factory packages.
+ *
+ * **ArkType is the single source of truth for the SPEC types here.** Every
+ * `*Spec` / config type below is inferred from the schema next to it
+ * (`typeof XSchema.infer`), which is the repository's integration contract: one
+ * definition validates at runtime, generates KRO SimpleSchema, and types the
+ * factory. The shapes were verified field-by-field against the CRDs installed
+ * by the Gateway API v1.2.1 experimental channel, read back from a live API
+ * server with `kubectl get crd <name> -o jsonpath='{.spec.versions[*].schema.openAPIV3Schema}'`.
+ *
+ * STATUS types stay hand-written interfaces: they describe what a controller
+ * publishes, never user input, so there is nothing to validate or generate.
+ *
+ * Where a schema is narrower than the CRD it is deliberate and noted inline
+ * (for example `listeners[].protocol`, which the CRD types as a bare string).
+ */
+import { type } from 'arktype';
+/**
+ * A Gateway API port.
+ *
+ * Every `port` in the API — listener, `parentRef`, `backendRef`,
+ * `requestRedirect` — carries `minimum: 1` / `maximum: 65535` in the CRD, so
+ * the bound is declared once here rather than repeated (or dropped) per field.
+ */
+const gatewayApiPort = '1 <= number.integer <= 65535';
+// ============================================================================
+// Shared schema shapes
+//
+// Extracted as `as const` shapes wherever a CRD repeats the same object at
+// several paths, so the definitions cannot drift apart.
+// ============================================================================
+/** An object reference restricted to Secrets (and, historically, ConfigMaps). */
+export const SecretObjectReferenceSchema = type({
+    'group?': 'string',
+    'kind?': 'string',
+    name: 'string',
+    'namespace?': 'string',
+});
+/** `GatewayClass.spec.parametersRef` — an implementation-specific config object. */
+const parametersRefShape = {
+    group: 'string',
+    kind: 'string',
+    name: 'string',
+    'namespace?': 'string',
+};
+/** A `metav1.LabelSelector` as Gateway API embeds it under `allowedRoutes`. */
+const labelSelectorShape = {
+    'matchLabels?': 'Record<string, string>',
+    'matchExpressions?': type({
+        key: 'string',
+        operator: 'string',
+        'values?': 'string[]',
+    }).array(),
+};
+/** An `HTTPRoute`/`GRPCRoute` header (and query-param) match. */
+const headerMatchShape = {
+    'type?': '"Exact" | "RegularExpression"',
+    name: 'string',
+    value: 'string',
+};
+/** One `name`/`value` pair of a header-modifier filter. */
+const headerValueShape = { name: 'string', value: 'string' };
+/** `filters[].requestRedirect.path` / `filters[].urlRewrite.path`. */
+const httpPathModifierShape = {
+    type: '"ReplaceFullPath" | "ReplacePrefixMatch"',
+    'replaceFullPath?': 'string',
+    'replacePrefixMatch?': 'string',
+};
+/** `sessionPersistence` — identical on `HTTPRoute` and `GRPCRoute` rules. */
+const sessionPersistenceShape = {
+    'sessionName?': 'string',
+    'absoluteTimeout?': 'string',
+    'idleTimeout?': 'string',
+    'type?': '"Cookie" | "Header"',
+    'cookieConfig?': {
+        'lifetimeType?': '"Permanent" | "Session"',
+    },
+};
+/** A CA-certificate reference, which unlike a Secret ref requires group/kind. */
+const caCertificateRefShape = {
+    group: 'string',
+    kind: 'string',
+    name: 'string',
+};
+// ============================================================================
+// GatewayClass
+// ============================================================================
+/** `GatewayClass.spec`. */
+export const GatewayClassSpecSchema = type({
+    controllerName: 'string',
+    'description?': 'string',
+    'parametersRef?': parametersRefShape,
+});
+// ============================================================================
+// Gateway
+// ============================================================================
+/** Which namespaces a listener accepts routes from. */
+export const AllowedRoutesSchema = type({
+    'namespaces?': {
+        'from?': '"All" | "Selector" | "Same"',
+        'selector?': labelSelectorShape,
+    },
+    'kinds?': type({
+        'group?': 'string',
+        kind: 'string',
+    }).array(),
+});
+/** `Gateway.spec.listeners[].tls`. */
+export const GatewayTLSConfigSchema = type({
+    'mode?': '"Terminate" | "Passthrough"',
+    'certificateRefs?': SecretObjectReferenceSchema.array(),
+    /** Client-certificate validation for a terminating listener. */
+    'frontendValidation?': {
+        'caCertificateRefs?': type({
+            ...caCertificateRefShape,
+            'namespace?': 'string',
+        }).array(),
+    },
+    'options?': 'Record<string, string>',
+});
+/**
+ * A single `Gateway.spec.listeners[]` entry.
+ *
+ * `protocol` is narrower than the CRD, which types it as a bare string: these
+ * five are the protocols the API defines, and an unknown protocol is rejected
+ * by every controller rather than doing something useful.
+ */
+export const GatewayListenerSchema = type({
+    name: 'string',
+    protocol: '"HTTP" | "HTTPS" | "TLS" | "TCP" | "UDP"',
+    port: gatewayApiPort,
+    'hostname?': 'string',
+    'tls?': GatewayTLSConfigSchema,
+    'allowedRoutes?': AllowedRoutesSchema,
+});
+/** A `Gateway.spec.addresses[]` entry. */
+const gatewayAddressShape = {
+    'type?': 'string',
+    value: 'string',
+};
+/** `Gateway.spec`. */
+export const GatewaySpecSchema = type({
+    gatewayClassName: 'string',
+    listeners: GatewayListenerSchema.array(),
+    'addresses?': type(gatewayAddressShape).array(),
+    'infrastructure?': {
+        'labels?': 'Record<string, string>',
+        'annotations?': 'Record<string, string>',
+        'parametersRef?': {
+            group: 'string',
+            kind: 'string',
+            name: 'string',
+        },
+    },
+    /** Default client certificate the Gateway presents to backends. */
+    'backendTLS?': {
+        'clientCertificateRef?': SecretObjectReferenceSchema,
+    },
+});
+// ============================================================================
+// Routes
+// ============================================================================
+/**
+ * A route's reference to the Gateway (or listener) it attaches to.
+ *
+ * `kind` stays a plain string, matching the CRD: the mesh profile allows a
+ * `Service` parent, so pinning the literal `'Gateway'` would reject a valid
+ * upstream shape.
+ */
+export const ParentReferenceSchema = type({
+    'group?': 'string',
+    'kind?': 'string',
+    name: 'string',
+    'namespace?': 'string',
+    'sectionName?': 'string',
+    'port?': gatewayApiPort,
+});
+/** A backend a route rule forwards to. */
+export const BackendRefSchema = type({
+    'group?': 'string',
+    'kind?': 'string',
+    name: 'string',
+    'namespace?': 'string',
+    'port?': gatewayApiPort,
+    /** Relative share of the rule's traffic. The CRD caps it at 1,000,000. */
+    'weight?': '0 <= number.integer <= 1000000',
+});
+/**
+ * One `HTTPRoute.spec.rules[].matches[]` entry.
+ *
+ * `path.value` is optional exactly as the CRD has it — an omitted value means
+ * the `/` prefix — and `method` uses the CRD's enum rather than a bare string.
+ */
+export const HTTPRouteMatchSchema = type({
+    'path?': {
+        'type?': '"Exact" | "PathPrefix" | "RegularExpression"',
+        'value?': 'string',
+    },
+    'headers?': type(headerMatchShape).array(),
+    'queryParams?': type(headerMatchShape).array(),
+    'method?': '"GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH"',
+});
+/** A header modification applied by an `HTTPRoute` filter. */
+export const HTTPHeaderFilterSchema = type({
+    'set?': type(headerValueShape).array(),
+    'add?': type(headerValueShape).array(),
+    'remove?': 'string[]',
+});
+/**
+ * One `HTTPRoute.spec.rules[].filters[]` entry.
+ *
+ * `extensionRef` is how an implementation attaches its own middleware — Traefik
+ * uses it to reference a `traefik.io/v1alpha1` `Middleware`.
+ */
+export const HTTPRouteFilterSchema = type({
+    type: '"RequestHeaderModifier" | "ResponseHeaderModifier" | "RequestMirror" | "RequestRedirect" | "URLRewrite" | "ExtensionRef"',
+    'requestHeaderModifier?': HTTPHeaderFilterSchema,
+    'responseHeaderModifier?': HTTPHeaderFilterSchema,
+    'requestRedirect?': {
+        'scheme?': '"http" | "https"',
+        'hostname?': 'string',
+        'port?': gatewayApiPort,
+        'statusCode?': '301 | 302',
+        'path?': httpPathModifierShape,
+    },
+    'urlRewrite?': {
+        'hostname?': 'string',
+        'path?': httpPathModifierShape,
+    },
+    'requestMirror?': {
+        backendRef: BackendRefSchema,
+        /** Mirror only a share of the requests. `percent` and `fraction` are exclusive. */
+        'percent?': '0 <= number.integer <= 100',
+        'fraction?': {
+            numerator: 'number.integer >= 0',
+            /** Defaults to 100 in the CRD, which also requires it to be positive. */
+            'denominator?': 'number.integer >= 1',
+        },
+    },
+    'extensionRef?': {
+        group: 'string',
+        kind: 'string',
+        name: 'string',
+    },
+});
+/** A `backendRefs[]` entry, which may carry its own per-backend filters. */
+const routeBackendRefSchema = BackendRefSchema.and({
+    'filters?': HTTPRouteFilterSchema.array(),
+});
+/** One `HTTPRoute.spec.rules[]` entry. */
+export const HTTPRouteRuleSchema = type({
+    'name?': 'string',
+    'matches?': HTTPRouteMatchSchema.array(),
+    'filters?': HTTPRouteFilterSchema.array(),
+    'backendRefs?': routeBackendRefSchema.array(),
+    'timeouts?': {
+        'request?': 'string',
+        'backendRequest?': 'string',
+    },
+    'retry?': {
+        /** Retriable response codes. The CRD admits 400-599. */
+        'codes?': '(400 <= number.integer <= 599)[]',
+        /** Unbounded in the CRD, so unbounded here. */
+        'attempts?': 'number.integer',
+        'backoff?': 'string',
+    },
+    'sessionPersistence?': sessionPersistenceShape,
+});
+/**
+ * `HTTPRoute.spec`.
+ *
+ * `parentRefs` is required here although the CRD allows it to be absent: a
+ * route attached to nothing serves no traffic, and TypeKro would have no
+ * resource to order it against.
+ */
+export const HTTPRouteSpecSchema = type({
+    parentRefs: ParentReferenceSchema.array(),
+    'hostnames?': 'string[]',
+    'rules?': HTTPRouteRuleSchema.array(),
+});
+/** One `GRPCRoute.spec.rules[].matches[]` entry. */
+export const GRPCRouteMatchSchema = type({
+    'method?': {
+        'type?': '"Exact" | "RegularExpression"',
+        'service?': 'string',
+        'method?': 'string',
+    },
+    'headers?': type(headerMatchShape).array(),
+});
+/**
+ * One `GRPCRoute.spec.rules[]` entry.
+ *
+ * The CRD accepts only the four filter types that make sense for gRPC
+ * (`RequestHeaderModifier`, `ResponseHeaderModifier`, `RequestMirror`,
+ * `ExtensionRef`) but reuses the HTTP filter shape, which is what
+ * {@link HTTPRouteFilterSchema} models.
+ */
+export const GRPCRouteRuleSchema = type({
+    'name?': 'string',
+    'matches?': GRPCRouteMatchSchema.array(),
+    'filters?': HTTPRouteFilterSchema.array(),
+    'backendRefs?': routeBackendRefSchema.array(),
+    'sessionPersistence?': sessionPersistenceShape,
+});
+/** `GRPCRoute.spec`. */
+export const GRPCRouteSpecSchema = type({
+    parentRefs: ParentReferenceSchema.array(),
+    'hostnames?': 'string[]',
+    'rules?': GRPCRouteRuleSchema.array(),
+});
+// ============================================================================
+// ReferenceGrant / BackendTLSPolicy
+// ============================================================================
+/**
+ * `ReferenceGrant.spec` — the opt-in a namespace publishes so resources in
+ * `from` namespaces may reference the listed `to` resources in this namespace.
+ */
+export const ReferenceGrantSpecSchema = type({
+    from: type({
+        group: 'string',
+        kind: 'string',
+        namespace: 'string',
+    }).array(),
+    to: type({
+        group: 'string',
+        kind: 'string',
+        'name?': 'string',
+    }).array(),
+});
+/**
+ * `BackendTLSPolicy.spec`.
+ *
+ * Kept general on purpose: Envoy Gateway targets its own `Backend` kind while
+ * other controllers target `Service`, so `targetRefs[].group`/`kind` are plain
+ * strings rather than one vendor's literals.
+ */
+export const BackendTLSPolicySpecSchema = type({
+    targetRefs: type({
+        group: 'string',
+        kind: 'string',
+        name: 'string',
+        'sectionName?': 'string',
+    }).array(),
+    validation: {
+        hostname: 'string',
+        'wellKnownCACertificates?': '"System"',
+        'caCertificateRefs?': type(caCertificateRefShape).array(),
+        'subjectAltNames?': type({
+            type: '"Hostname" | "URI"',
+            'hostname?': 'string',
+            'uri?': 'string',
+        }).array(),
+    },
+    'options?': 'Record<string, string>',
+});
+// ============================================================================
+// Resource configuration
+//
+// The identity half of every Gateway API factory's config. `spec` is the only
+// part that varies by kind, so it stays a type parameter (see
+// `resources/gateway.ts`) while everything a caller types by hand is declared
+// once, here, and inferred from.
+// ============================================================================
+const kubernetesName = type(/^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$/).and('string <= 253');
+const kubernetesDnsLabel = type(/^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$/).and('string <= 63');
+/**
+ * Identity fields every Gateway API resource factory accepts.
+ *
+ * These schemas are the source of truth for the TYPES and the target of the
+ * schema tests; the factories do not run them over their input, because inside
+ * a composition `name` may be a `KubernetesRef` proxy rather than a string and
+ * every constraint here would reject it.
+ */
+export const gatewayApiClusterResourceMetadataShape = {
+    name: kubernetesName,
+    /** Extra labels merged onto `metadata.labels`. */
+    'labels?': 'Record<string, string>',
+    /** Extra annotations merged onto `metadata.annotations`. */
+    'annotations?': 'Record<string, string>',
+    /** Resource graph id. Required when `name` is a schema reference. */
+    'id?': 'string > 0',
+};
+/** Identity fields every namespaced Gateway API resource factory accepts. */
+export const gatewayApiNamespacedResourceMetadataShape = {
+    ...gatewayApiClusterResourceMetadataShape,
+    namespace: kubernetesDnsLabel,
+};
+/** Identity of a cluster-scoped Gateway API resource, without its spec. */
+export const GatewayApiClusterResourceMetadataSchema = type(gatewayApiClusterResourceMetadataShape);
+/** Identity of a namespaced Gateway API resource, without its spec. */
+export const GatewayApiNamespacedResourceMetadataSchema = type(gatewayApiNamespacedResourceMetadataShape);
+/**
+ * Configuration for `backendTLSPolicy`.
+ *
+ * Fully inferred rather than generic: a `BackendTLSPolicy` has exactly one
+ * spec shape, so there is nothing for a type parameter to vary.
+ */
+export const BackendTLSPolicyConfigSchema = type({
+    ...gatewayApiNamespacedResourceMetadataShape,
+    /**
+     * The `GatewayClass.spec.controllerName` whose ancestor conditions decide
+     * readiness. A cluster can run several Gateway API controllers, and each one
+     * publishes its own ancestor entry.
+     */
+    controllerName: 'string > 0',
+    spec: BackendTLSPolicySpecSchema,
+});
+//# sourceMappingURL=types.js.map

package/dist/factories/gateway-api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/factories/gateway-api/types.ts"],"names":[],"mappings":"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"}

package/dist/factories/helm/readiness-evaluators.d.ts

@@ -8,9 +8,27 @@ import type { ReadinessEvaluator } from '../../core/types/index.js';
 /**
  * Create a readiness evaluator for HelmRelease resources.
  *
- * Checks multiple readiness criteria in priority order: status phase,
- * Flux CD conditions array, and installation/upgrade progress. Wraps
- * the evaluation in a try/catch for resilience.
+ * READINESS CONTRACT (tightened by issue #191). A HelmRelease is ready only
+ * when ALL of the following hold, checked in this order:
+ *
+ * 1. `status` exists at all (Flux adds it a beat after creation).
+ * 2. Every generation-bearing observation Flux publishes — the top-level
+ *    `status.observedGeneration` and the `Ready`/`Released` conditions' own —
+ *    is EXACTLY `metadata.generation`. Readiness evidence from a neighbouring
+ *    generation describes a different spec.
+ * 3. `Reconciling` is not `True`. Flux holds that condition for the whole
+ *    install/upgrade, so a `Ready=True` beside it belongs to the PREVIOUS
+ *    release — the state that made `waitForReady` on a Helm-backed bootstrap
+ *    return before the chart's workloads existed.
+ * 4. `Stalled` is not `True` (a stalled release does not retry itself).
+ * 5. The revision Flux last ATTEMPTED (`status.lastAttemptedRevision`) is the
+ *    revision actually released (`status.history[0].chartVersion`, or the
+ *    beta-shape `status.lastAppliedRevision`). A failed upgrade that
+ *    remediates leaves the older chart deployed with a `Ready=True` that must
+ *    not read as success.
+ * 6. A present `Released` condition is `True`.
+ * 7. Then, and only then, the legacy `status.phase` and the Flux v2 `Ready`
+ *    condition decide readiness.
  *
  * @param label - Optional label prefix for log messages (e.g., `'Cert-Manager'`).
  *   Defaults to no prefix (`'HelmRelease'`).

package/dist/factories/helm/readiness-evaluators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"readiness-evaluators.d.ts","sourceRoot":"","sources":["../../../src/factories/helm/readiness-evaluators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,2BAA2B,CAAC;AAuBnC;;;;;;;;;;;;GAYG;AAEH,wBAAgB,iCAAiC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CA6H7F;AAED;;;;GAIG;AAEH,eAAO,MAAM,6BAA6B,EAAE,kBAAkB,CAAC,OAAO,CACjC,CAAC;AAEtC;;;;;;;GAOG;AAEH,wBAAgB,oCAAoC,CAClD,gBAAgB,EAAE,MAAM,GACvB,kBAAkB,CAAC,OAAO,CAAC,CA2C7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,GAAE,OAAe,GAE5B,kBAAkB,CAAC,OAAO,CAAC,CA+D7B;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,GAAE,MAAW,GAE1B,kBAAkB,CAAC,OAAO,CAAC,CAoD7B;AAED;;;;;;;GAOG;AACH,wBAAgB,yCAAyC,CACvD,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3F,kBAAkB,CAAC,OAAO,CAAC,CA0D7B"}
+{"version":3,"file":"readiness-evaluators.d.ts","sourceRoot":"","sources":["../../../src/factories/helm/readiness-evaluators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,2BAA2B,CAAC;AAuEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,wBAAgB,iCAAiC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CA8L7F;AAED;;;;GAIG;AAEH,eAAO,MAAM,6BAA6B,EAAE,kBAAkB,CAAC,OAAO,CACjC,CAAC;AAEtC;;;;;;;GAOG;AAEH,wBAAgB,oCAAoC,CAClD,gBAAgB,EAAE,MAAM,GACvB,kBAAkB,CAAC,OAAO,CAAC,CA2C7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,GAAE,OAAe,GAE5B,kBAAkB,CAAC,OAAO,CAAC,CA+D7B;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,GAAE,MAAW,GAE1B,kBAAkB,CAAC,OAAO,CAAC,CAoD7B;AAED;;;;;;;GAOG;AACH,wBAAgB,yCAAyC,CACvD,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3F,kBAAkB,CAAC,OAAO,CAAC,CA0D7B"}

package/dist/factories/helm/readiness-evaluators.js

@@ -10,13 +10,61 @@ import { optionalReadinessString, readinessConfiguration, readinessLiteral, requ
 const HELM_RELEASE_STRATEGY = 'typekro.readiness.flux.helm-release';
 const HELM_RELEASE_REVISION_STRATEGY = 'typekro.readiness.flux.helm-release-revision';
 const HELM_RELEASE_TEST_STRATEGY = 'typekro.readiness.flux.helm-release-test';
-const HELM_READINESS_REVISION = '1';
+/**
+ * Bumped to '2' with the #191 tightening (Reconciling/Stalled gating, exact
+ * generation observation, released-revision currency). The revision is part of
+ * the portable strategy identity, so a graph serialized by an older TypeKro
+ * cannot silently rehydrate the looser evaluator.
+ */
+const HELM_READINESS_REVISION = '2';
+/** Flux condition types this evaluator gates on, beyond `Ready`. */
+const RECONCILING_CONDITION = 'Reconciling';
+const STALLED_CONDITION = 'Stalled';
+const RELEASED_CONDITION = 'Released';
+function findCondition(conditions, type) {
+    return conditions?.find((condition) => condition.type === type);
+}
+/**
+ * The chart revision Flux has actually RELEASED, across both v2 status shapes.
+ *
+ * Flux v2 GA keeps a `history` snapshot stack (newest first); the beta shape
+ * exposed a single `lastAppliedRevision`. Either is compared against
+ * `lastAttemptedRevision` to tell "the attempt succeeded" from "the attempt
+ * failed and an older release is still what is installed".
+ */
+function releasedRevision(status) {
+    const fromHistory = status.history?.[0]?.chartVersion;
+    if (typeof fromHistory === 'string' && fromHistory !== '')
+        return fromHistory;
+    const applied = status.lastAppliedRevision;
+    if (typeof applied === 'string' && applied !== '')
+        return applied;
+    return undefined;
+}
 /**
  * Create a readiness evaluator for HelmRelease resources.
  *
- * Checks multiple readiness criteria in priority order: status phase,
- * Flux CD conditions array, and installation/upgrade progress. Wraps
- * the evaluation in a try/catch for resilience.
+ * READINESS CONTRACT (tightened by issue #191). A HelmRelease is ready only
+ * when ALL of the following hold, checked in this order:
+ *
+ * 1. `status` exists at all (Flux adds it a beat after creation).
+ * 2. Every generation-bearing observation Flux publishes — the top-level
+ *    `status.observedGeneration` and the `Ready`/`Released` conditions' own —
+ *    is EXACTLY `metadata.generation`. Readiness evidence from a neighbouring
+ *    generation describes a different spec.
+ * 3. `Reconciling` is not `True`. Flux holds that condition for the whole
+ *    install/upgrade, so a `Ready=True` beside it belongs to the PREVIOUS
+ *    release — the state that made `waitForReady` on a Helm-backed bootstrap
+ *    return before the chart's workloads existed.
+ * 4. `Stalled` is not `True` (a stalled release does not retry itself).
+ * 5. The revision Flux last ATTEMPTED (`status.lastAttemptedRevision`) is the
+ *    revision actually released (`status.history[0].chartVersion`, or the
+ *    beta-shape `status.lastAppliedRevision`). A failed upgrade that
+ *    remediates leaves the older chart deployed with a `Ready=True` that must
+ *    not read as success.
+ * 6. A present `Released` condition is `True`.
+ * 7. Then, and only then, the legacy `status.phase` and the Flux v2 `Ready`
+ *    condition decide readiness.
  *
  * @param label - Optional label prefix for log messages (e.g., `'Cert-Manager'`).
  *   Defaults to no prefix (`'HelmRelease'`).
@@ -43,20 +91,24 @@ export function createLabeledHelmReleaseEvaluator(label) {
             // An apply can advance metadata.generation before Flux has observed the
             // new spec. Never reuse readiness evidence from the preceding
             // generation: doing so makes a direct factory update return while Flux
-            // is still reconciling the replacement values. Prefer the top-level
-            // observedGeneration and also honor generation-aware Ready conditions
-            // when the controller supplies them.
+            // is still reconciling the replacement values. Every generation-bearing
+            // observation Flux publishes — the top-level `observedGeneration` and
+            // the `Ready`/`Released` conditions' own — must be EXACTLY the desired
+            // generation (#191): a lagging one is stale evidence, and an
+            // unexpectedly leading one is not evidence about this spec at all.
             const desiredGeneration = live.metadata?.generation;
-            const readyCondition = status.conditions?.find((condition) => condition.type === 'Ready');
+            const readyCondition = findCondition(status.conditions, 'Ready');
+            const releasedCondition = findCondition(status.conditions, RELEASED_CONDITION);
             const observedGenerations = [
                 status.observedGeneration,
                 readyCondition?.observedGeneration,
+                releasedCondition?.observedGeneration,
             ].filter((generation) => typeof generation === 'number');
-            const staleGenerations = typeof desiredGeneration === 'number'
-                ? observedGenerations.filter((generation) => generation < desiredGeneration)
+            const mismatchedGenerations = typeof desiredGeneration === 'number'
+                ? observedGenerations.filter((generation) => generation !== desiredGeneration)
                 : [];
             if (typeof desiredGeneration === 'number' &&
-                (observedGenerations.length === 0 || staleGenerations.length > 0)) {
+                (observedGenerations.length === 0 || mismatchedGenerations.length > 0)) {
                 return {
                     ready: false,
                     reason: 'GenerationNotObserved',
@@ -69,6 +121,60 @@ export function createLabeledHelmReleaseEvaluator(label) {
                     },
                 };
             }
+            // #191: Flux keeps `Reconciling=True` for the WHOLE duration of an
+            // install/upgrade and removes it when the release settles. A `Ready`
+            // condition (or a legacy `phase`) that co-exists with it describes the
+            // PREVIOUS release, so an in-flight reconcile is never ready — this is
+            // the state that let `waitForReady` return ~90s before the ClickHouse
+            // operator's chart had actually installed.
+            const reconciling = findCondition(status.conditions, RECONCILING_CONDITION);
+            if (reconciling?.status === 'True') {
+                return {
+                    ready: false,
+                    reason: 'Reconciling',
+                    message: reconciling.message ??
+                        `${prefix}HelmRelease is still reconciling (Reconciling=True), so any Ready ` +
+                            `condition describes the preceding release`,
+                };
+            }
+            // A stalled release will not retry on its own; surface it as a failure
+            // rather than letting the caller wait out its timeout.
+            const stalled = findCondition(status.conditions, STALLED_CONDITION);
+            if (stalled?.status === 'True') {
+                return {
+                    ready: false,
+                    reason: stalled.reason ?? 'Stalled',
+                    message: stalled.message ?? `${prefix}HelmRelease is stalled and will not retry`,
+                };
+            }
+            // #191: the release Flux last ATTEMPTED must be the release that is
+            // actually installed. A failed upgrade that remediates leaves the older
+            // chart deployed (`history[0].chartVersion`) while
+            // `lastAttemptedRevision` names the version that failed — the exact
+            // shape where a lingering `Ready=True` would otherwise read as success.
+            const attemptedRevision = status.lastAttemptedRevision;
+            const currentRevision = releasedRevision(status);
+            if (typeof attemptedRevision === 'string' &&
+                attemptedRevision !== '' &&
+                currentRevision !== undefined &&
+                attemptedRevision !== currentRevision) {
+                return {
+                    ready: false,
+                    reason: 'RevisionNotReleased',
+                    message: `${prefix}HelmRelease last attempted revision ${attemptedRevision} but the ` +
+                        `released revision is still ${currentRevision}`,
+                    details: { attemptedRevision, releasedRevision: currentRevision },
+                };
+            }
+            // A `Released` condition that is present and not True means the chart
+            // was not handed to Helm successfully, whatever `Ready` says.
+            if (releasedCondition !== undefined && releasedCondition.status !== 'True') {
+                return {
+                    ready: false,
+                    reason: releasedCondition.reason ?? 'NotReleased',
+                    message: releasedCondition.message ?? `${prefix}HelmRelease has not released its chart yet`,
+                };
+            }
             // Case 2: Check the phase of the HelmRelease (primary readiness indicator)
             if (status.phase === 'Ready') {
                 return {