@gajae-code/ai 0.1.1

package/src/utils/schema/CONSTRAINTS.md

@@ -0,0 +1,164 @@
+# Schema Constraints
+
+This document is the operational contract for schema normalization/strictness in `packages/ai/src/utils/schema`.
+
+## Scope
+
+- Applies to provider-facing tool schemas produced by:
+  - `normalize.ts` — Google, CCA, MCP, OpenAI Responses, and OpenAI strict-mode (sanitize + enforce) sanitization. All schema walkers live here.
+  - `adapt.ts` — thin composer wrapping `tryEnforceStrictSchema` for provider call sites, plus the `PI_NO_STRICT` env flag callers consult to opt out of strict mode.
+  - `fields.ts` — keyword classification sets used by the walkers.
+- Covers OpenAI-style strict mode, OpenAI Responses `oneOf` rejection, Google schema constraints, and Cloud Code Assist Anthropic constraints.
+---
+
+## 1) OpenAI-style strict mode (`adaptSchemaForStrict` / `tryEnforceStrictSchema`)
+
+When strict mode is requested (`strict=true` at call site), the schema MUST satisfy all of the following after adaptation:
+
+1. **Non-structural keywords are removed before strict enforcement**
+   - Sanitization uses `sanitizeSchemaForStrictMode`.
+   - Removed keys include formatting/validation/decorative keywords and unsupported structural extras:
+     - `format`, `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
+     - `minItems`, `maxItems`, `uniqueItems`, `multipleOf`
+     - `$schema`, `examples`, `default`, `title`, `$comment`
+     - `if`, `then`, `else`, `not`
+     - `unevaluatedProperties`, `unevaluatedItems`, `patternProperties`
+     - `propertyNames`, `contains`, `minContains`, `maxContains`
+     - `dependentRequired`, `dependentSchemas`
+     - `contentEncoding`, `contentMediaType`, `contentSchema`
+     - `deprecated`, `readOnly`, `writeOnly`
+     - `minProperties`, `maxProperties`
+     - `$dynamicRef`, `$dynamicAnchor`
+   - Before stripping `default`, its value is inlined into the sibling `description` as ` (default: X)` so that strict-mode providers retain the default hint in free-form text. Inlining is skipped when `description` already contains `(default:` or when no sibling `description` is present.
+
+2. **`const` is normalized to `enum`**
+   - If a node contains `const`, strict sanitization converts it to `enum: [const]`.
+
+3. **Object and tuple strictness is enforced recursively**
+   - Every object node gets `additionalProperties: false`.
+   - Every property key is included in `required`.
+   - Optional properties are wrapped as nullable unions:
+     - `anyOf: [<original schema>, { "type": "null" }]`.
+   - Tuple entries in `prefixItems` are strictified recursively.
+
+4. **Schema nodes must be representable in strict mode**
+   - Nodes without `type`, combinator, `$ref`, or `not` are invalid in strict enforcement and MUST throw.
+   - Example invalid node: `{}` or `{ items: {} }`.
+
+5. **Failure mode is fail-open to non-strict**
+   - `tryEnforceStrictSchema` MUST return `{ strict: false, schema: original }` when strict enforcement throws.
+   - It MUST NOT emit partially-broken strict schema.
+
+6. **Provider payload strict flag must match effective strictness**
+   - Callers MUST send `strict: true` only if enforcement succeeded (`effectiveStrict === true`).
+
+---
+
+## 2) Google Gemini / Vertex / Gemini CLI (`normalizeSchemaForGoogle`)
+
+Schemas sent on the Google JSON Schema path MUST follow:
+
+1. **Unsupported JSON Schema keywords are stripped (except property names under `properties`)**
+   - Unsupported keys (`UNSUPPORTED_SCHEMA_FIELDS`):
+     - `$schema`, `$ref`, `$defs`, `$dynamicRef`, `$dynamicAnchor`
+     - `examples`, `prefixItems`, `unevaluatedProperties`, `unevaluatedItems`
+     - `patternProperties`, `additionalProperties`
+     - `minItems`, `maxItems`, `minLength`, `maxLength`
+     - `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
+     - `pattern`, `format`
+   - Important: keys inside a `properties` object are treated as property names and MUST NOT be stripped by keyword match.
+   - Human-meaningful stripped keys (`pattern`, `format`, min/max constraints, `default`, `examples`, etc.) are appended to the sibling `description` as an Anthropic-style spill block: `{pattern: "^foo$", minimum: 0}`. Structural/meta keys such as `$ref`, `$defs`, and `additionalProperties` are not spilled.
+
+2. **`type` arrays are normalized to scalar type + nullable marker**
+   - `type: ["T", "null"]` becomes `type: "T"` and `nullable: true`.
+   - Google expects scalar type, not `type[]`.
+
+3. **`const` is converted to `enum`**
+   - If `const` exists, schema uses/merges `enum` with the const value.
+
+4. **Object schemas get an explicit properties map**
+   - `{ "type": "object" }` becomes `{ "type": "object", "properties": {} }`.
+---
+
+## 3) Anthropic model via Cloud Code Assist (`normalizeSchemaForCCA`)
+
+For Cloud Code Assist Anthropic tool declarations, schema MUST satisfy stricter constraints than generic Google path.
+
+### 3.1 Transport contract
+
+1. **Use legacy `parameters` field** (not `parametersJsonSchema`) for CCA Anthropic model.
+2. CCA path uses the full `normalizeSchemaForCCA` pipeline.
+
+### 3.2 Sanitization contract
+
+1. Start with Google unsupported-key stripping behavior.
+2. **`nullable` keyword MUST be stripped** in CCA Anthropic model path.
+3. `type: ["T", "null"]` becomes `type: "T"` with no `nullable` marker.
+4. Human-meaningful stripped keys are appended to `description` with the same spill format used by the Google dispatcher.
+
+### 3.3 Combiner/union normalization contract
+
+1. Object-only `anyOf`/`oneOf` variants SHOULD be merged into a single object shape where safe.
+2. Same-type combiner variants SHOULD be collapsed to one schema.
+3. Mixed-type combiner variants MAY be lossy-collapsed to first non-null scalar type when required for CCA acceptance.
+4. Residual combiners are recursively stripped where collapsible (`stripResidualCombiners`).
+
+### 3.4 Nullable property normalization contract
+
+1. Property-local nullability expressed as:
+   - `nullable: true`, or
+   - `type` union including `null`, or
+   - `anyOf`/`oneOf` with one `{ "type": "null" }` branch
+     MUST be converted to non-required property semantics where possible.
+2. If a property is detected nullable after normalization, it MUST be removed from `required`.
+
+### 3.5 Residual incompatibility gate (hard stop)
+
+After normalization, schema MUST NOT contain any of:
+
+- `type` as array
+- `type: "null"`
+- `nullable` key
+- `anyOf`, `oneOf`, `allOf` arrays
+
+If any remain, schema is incompatible.
+
+### 3.6 Validation + fallback contract
+
+1. Normalized schema is validated with AJV 2020 schema validation.
+2. If invalid OR residual incompatibilities exist, output MUST fallback to:
+
+```json
+{ "type": "object", "properties": {} }
+```
+
+3. Fallback is per-tool and fail-open; one bad tool schema MUST NOT fail the whole request.
+
+---
+
+## 4) Practical provider mapping
+
+- **OpenAI-compatible strict paths** (`openai-completions`, `openai-responses`, `openai-code-responses`):
+  - Use `adaptSchemaForStrict`.
+  - Emit `strict: true` only when effective strict enforcement succeeded.
+
+- **Google Gemini/Vertex/Gemini CLI (non-CCA Anthropic model)**:
+  - Use `normalizeSchemaForGoogle` and send schema on `parametersJsonSchema` path.
+
+- **Cloud Code Assist Anthropic models (`model.id` starts with `anthropic-model-`)**:
+  - Use `normalizeSchemaForCCA` and send sanitized normalized schema in `parameters`.
+
+---
+
+## 5) Maintenance rules
+
+When adding/changing provider adapters:
+
+1. Any new unsupported keyword MUST be added to the appropriate set in `fields.ts`.
+2. Any new normalization rule MUST include regression tests under `packages/ai/test`.
+3. Never bypass adapter helpers (`adaptSchemaForStrict`, `normalizeSchemaForGoogle`, `normalizeSchemaForCCA`, `normalizeSchemaForMCP`) in provider code.
+4. If a provider rejects schema with partial support, prefer deterministic per-tool fallback over request-wide failure.
+
+## 6) Gemini CLI / Antigravity CCA parity
+
+The Gemini CLI / Antigravity Anthropic model path MUST run the same full `normalizeSchemaForCCA` pipeline as the shared Google Anthropic path. It MUST NOT call only the first keyword-stripping pass, because that leaves object combiners, nullable unions, residual combiners, and fallback gating inconsistent between transports.

package/src/utils/schema/adapt.ts

@@ -0,0 +1,36 @@
+import { $flag } from "@gajae-code/utils";
+import { upgradeJsonSchemaTo202012 } from "./draft";
+import { tryEnforceStrictSchema } from "./normalize";
+
+/**
+ * Set when callers want to globally bypass OpenAI strict-mode enforcement
+ * (e.g. for debugging a provider that misreports strict support, or when
+ * comparing strict vs non-strict outputs).
+ *
+ * Honored by every provider that emits `strict: true` on its function tools —
+ * see `openai-completions`, `openai-responses`, `OpenAI code provider-responses`, and
+ * the strict candidate selection in `anthropic`.
+ */
+export const NO_STRICT = $flag("PI_NO_STRICT");
+
+/**
+ * Consolidated helper for OpenAI-style strict schema enforcement.
+ *
+ * Each provider computes its own `strict` boolean (logic differs), then calls
+ * this to handle the tryEnforceStrictSchema dance uniformly:
+ * - Draft-07-shaped inputs are upgraded to draft 2020-12 first.
+ * - If `strict` is false, passes the upgraded schema through unchanged.
+ * - If `strict` is true, attempts to enforce strict mode; falls back to
+ *   non-strict if the schema isn't representable.
+ */
+export function adaptSchemaForStrict(
+	schema: Record<string, unknown>,
+	strict: boolean,
+): { schema: Record<string, unknown>; strict: boolean } {
+	const upgraded = upgradeJsonSchemaTo202012(schema) as Record<string, unknown>;
+	if (!strict) {
+		return { schema: upgraded, strict: false };
+	}
+
+	return tryEnforceStrictSchema(upgraded);
+}

package/src/utils/schema/compatibility.ts

@@ -0,0 +1,435 @@
+import {
+	CCA_UNSUPPORTED_SCHEMA_FIELDS,
+	COMBINATOR_KEYS,
+	NON_STRUCTURAL_SCHEMA_KEYS,
+	UNSUPPORTED_SCHEMA_FIELDS,
+} from "./fields";
+import { isValidJsonSchema } from "./meta-validator";
+import { isJsonObject, type JsonObject } from "./types";
+
+/**
+ * Schema compatibility audits.
+ *
+ * Each provider has a different idea of what JSON Schema features it accepts
+ * for tool definitions. The normalizers in `normalize.ts`, `strict-mode`,
+ * and `adapt.ts` rewrite incoming schemas to fit. This module is the
+ * *audit* counterpart: it walks a (presumably already-sanitized) schema and
+ * reports any feature the target provider would reject. Tests use it to lock
+ * down the contract; the runtime uses it to fail-open with diagnostic logs
+ * rather than silently shipping a broken tool definition.
+ */
+export type SchemaCompatibilityProvider = "openai-strict" | "google" | "cloud-code-assist-claude";
+
+export interface SchemaCompatibilityViolation {
+	path: string;
+	rule: string;
+	message: string;
+	key?: string;
+	value?: unknown;
+}
+
+export interface SchemaCompatibilityResult {
+	provider: SchemaCompatibilityProvider;
+	compatible: boolean;
+	violations: SchemaCompatibilityViolation[];
+}
+
+export interface StrictSchemaEnforcementResult {
+	schema: Record<string, unknown>;
+	strict: boolean;
+}
+
+// Per-provider forbidden-key sets. Subsets of the shared `fields.ts` constants
+// plus a few provider-specific extras (`const`, `nullable`) folded in here so
+// each rule is defined in exactly one place.
+const STRICT_FORBIDDEN_KEYS: Record<string, true> = { ...NON_STRUCTURAL_SCHEMA_KEYS, const: true, nullable: true };
+const GOOGLE_FORBIDDEN_KEYS: Record<string, true> = { ...UNSUPPORTED_SCHEMA_FIELDS, const: true };
+const CCA_FORBIDDEN_KEYS: Record<string, true> = { ...CCA_UNSUPPORTED_SCHEMA_FIELDS, const: true };
+
+// Keys whose values are JSON-Schema *containers* (arrays of values, scalars,
+// etc.) rather than nested schemas. The traversal must skip these — recursing
+// would walk into `enum` strings or `default` objects and emit spurious
+// violations against keys that happen to share JSON-Schema keyword names.
+const NON_SCHEMA_CONTAINER_ARRAY_KEYS: Record<string, true> = {
+	enum: true,
+	required: true,
+	examples: true,
+	type: true,
+};
+const NON_SCHEMA_CONTAINER_OBJECT_KEYS: Record<string, true> = { const: true, default: true, example: true };
+
+interface TraversalState {
+	path: string;
+}
+
+function createViolation(
+	path: string,
+	rule: string,
+	message: string,
+	key?: string,
+	value?: unknown,
+): SchemaCompatibilityViolation {
+	return {
+		path,
+		rule,
+		message,
+		...(key === undefined ? {} : { key }),
+		...(value === undefined ? {} : { value }),
+	};
+}
+
+/**
+ * Recursively visit every schema node in a JSON Schema tree.
+ *
+ * The walker is *structural*, not type-aware: it knows which keywords contain
+ * nested schemas vs. plain values, so it descends into `properties.*`,
+ * `$defs.*`, `items`, combinator arrays, etc. but never into `enum`, `const`,
+ * `default`, or `type` arrays.
+ */
+function walkSchema(
+	value: unknown,
+	state: TraversalState,
+	visitNode: (node: JsonObject, state: TraversalState) => void,
+): void {
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index++) {
+			walkSchema(value[index], { path: `${state.path}[${index}]` }, visitNode);
+		}
+		return;
+	}
+
+	if (!isJsonObject(value)) {
+		return;
+	}
+
+	visitNode(value, state);
+
+	for (const key in value) {
+		// Schema-map keywords: value is `{ name: schema, … }`. Recurse into each
+		// entry's schema rather than the map object itself.
+		const entry = value[key];
+		if (key === "properties" || key === "$defs" || key === "definitions" || key === "dependentSchemas") {
+			if (isJsonObject(entry)) {
+				for (const name in entry) {
+					const child = entry[name];
+					walkSchema(child, { path: `${state.path}.${key}.${name}` }, visitNode);
+				}
+			}
+			continue;
+		}
+		// Non-schema container keywords — values are not schemas, do not descend.
+
+		if (key in NON_SCHEMA_CONTAINER_ARRAY_KEYS || key in NON_SCHEMA_CONTAINER_OBJECT_KEYS) {
+			continue;
+		}
+		// Array-of-schemas keywords (e.g. `allOf`, `anyOf`, `oneOf`, `prefixItems`).
+
+		if (Array.isArray(entry)) {
+			for (let index = 0; index < entry.length; index++) {
+				walkSchema(entry[index], { path: `${state.path}.${key}[${index}]` }, visitNode);
+			}
+			continue;
+		}
+
+		if (isJsonObject(entry)) {
+			walkSchema(entry, { path: `${state.path}.${key}` }, visitNode);
+		}
+	}
+}
+
+/**
+ * Strict-mode audit (OpenAI Responses / OpenAI code backend `strict: true`):
+ *  1. Forbid keywords that strict mode disallows (`format`, `pattern`, `const`,
+ *     `nullable`, etc. — see `STRICT_FORBIDDEN_KEYS`).
+ *  2. Every node must declare *something* concrete: a `type`, a combinator,
+ *     a `$ref`, or a `not` branch. Empty `{}` is rejected.
+ *  3. Object nodes must set `additionalProperties: false`, declare a real
+ *     `properties` map, and require every property in that map. Required
+ *     properties not in `properties` are also rejected — strict mode demands
+ *     a closed object shape.
+ */
+function validateStrictNode(node: JsonObject, state: TraversalState): SchemaCompatibilityViolation[] {
+	const violations: SchemaCompatibilityViolation[] = [];
+
+	for (const key in node) {
+		const value = node[key];
+		if (!(key in STRICT_FORBIDDEN_KEYS)) {
+			continue;
+		}
+
+		violations.push(
+			createViolation(
+				`${state.path}.${key}`,
+				"strict-forbidden-key",
+				`Strict schema contains forbidden key "${key}"`,
+				key,
+				value,
+			),
+		);
+	}
+	// Rule 2: node must declare at least one concrete shape descriptor.
+
+	const hasCombinator = COMBINATOR_KEYS.some(key => Array.isArray(node[key]));
+	const hasRef = typeof node.$ref === "string";
+	const hasNot = isJsonObject(node.not);
+	if (node.type === undefined && !hasCombinator && !hasRef && !hasNot) {
+		violations.push(
+			createViolation(
+				state.path,
+				"strict-unrepresentable-node",
+				"Strict schema node must declare type, combinator, $ref, or not",
+			),
+		);
+	}
+	// Rules 3a-3d apply only to object-shaped nodes.
+
+	const isObjectNode = node.type === "object" || isJsonObject(node.properties);
+	if (!isObjectNode) {
+		return violations;
+	}
+
+	if (node.additionalProperties !== false) {
+		violations.push(
+			createViolation(
+				`${state.path}.additionalProperties`,
+				"strict-object-additional-properties",
+				"Strict object schema must set additionalProperties to false",
+				"additionalProperties",
+				node.additionalProperties,
+			),
+		);
+	}
+	// 3b: `properties` must exist and be an object — without it strict mode has nothing to validate.
+
+	if (!isJsonObject(node.properties)) {
+		violations.push(
+			createViolation(
+				`${state.path}.properties`,
+				"strict-object-properties",
+				"Strict object schema must provide an object-valued properties map",
+				"properties",
+				node.properties,
+			),
+		);
+		return violations;
+	}
+
+	const propertyNames = Object.keys(node.properties);
+	const requiredValues = Array.isArray(node.required)
+		? node.required.filter((entry): entry is string => typeof entry === "string")
+		: [];
+	const requiredSet = new Set(requiredValues);
+
+	for (const propertyName of propertyNames) {
+		if (requiredSet.has(propertyName)) {
+			continue;
+		}
+		violations.push(
+			createViolation(
+				`${state.path}.required`,
+				"strict-object-required",
+				`Strict object schema must require property "${propertyName}"`,
+				"required",
+				node.required,
+			),
+		);
+	}
+	// 3d: any property declared in `required` but missing from `properties` is unrepresentable.
+
+	const propertyNameSet = new Set(propertyNames);
+	for (const requiredKey of requiredValues) {
+		if (propertyNameSet.has(requiredKey)) {
+			continue;
+		}
+		violations.push(
+			createViolation(
+				`${state.path}.required`,
+				"strict-object-required-extra",
+				`Strict object schema requires non-existent property "${requiredKey}"`,
+				"required",
+				node.required,
+			),
+		);
+	}
+
+	return violations;
+}
+
+function validateGoogleNode(node: JsonObject, state: TraversalState): SchemaCompatibilityViolation[] {
+	const violations: SchemaCompatibilityViolation[] = [];
+
+	for (const key in node) {
+		const value = node[key];
+		if (!(key in GOOGLE_FORBIDDEN_KEYS)) {
+			continue;
+		}
+		violations.push(
+			createViolation(
+				`${state.path}.${key}`,
+				"google-forbidden-key",
+				`Google schema contains unsupported key "${key}"`,
+				key,
+				value,
+			),
+		);
+	}
+
+	if (Array.isArray(node.type)) {
+		violations.push(
+			createViolation(
+				`${state.path}.type`,
+				"google-type-array",
+				"Google schema type must be a scalar string, not an array",
+				"type",
+				node.type,
+			),
+		);
+	}
+
+	return violations;
+}
+
+function validateCloudCodeAssistNode(node: JsonObject, state: TraversalState): SchemaCompatibilityViolation[] {
+	const violations: SchemaCompatibilityViolation[] = [];
+
+	for (const key in node) {
+		const value = node[key];
+		if (key in CCA_FORBIDDEN_KEYS) {
+			violations.push(
+				createViolation(
+					`${state.path}.${key}`,
+					"cca-forbidden-key",
+					`Cloud Code Assist schema contains unsupported key "${key}"`,
+					key,
+					value,
+				),
+			);
+		}
+	}
+
+	if (Array.isArray(node.type)) {
+		violations.push(
+			createViolation(
+				`${state.path}.type`,
+				"cca-type-array",
+				"Cloud Code Assist schema forbids array-valued type",
+				"type",
+				node.type,
+			),
+		);
+	}
+
+	if (node.type === "null") {
+		violations.push(
+			createViolation(
+				`${state.path}.type`,
+				"cca-null-type",
+				'Cloud Code Assist schema forbids type: "null"',
+				"type",
+				node.type,
+			),
+		);
+	}
+
+	if (Object.hasOwn(node, "nullable")) {
+		violations.push(
+			createViolation(
+				`${state.path}.nullable`,
+				"cca-nullable-key",
+				"Cloud Code Assist schema forbids nullable keyword",
+				"nullable",
+				node.nullable,
+			),
+		);
+	}
+
+	for (const key of COMBINATOR_KEYS) {
+		if (Array.isArray(node[key])) {
+			violations.push(
+				createViolation(
+					`${state.path}.${key}`,
+					"cca-combiner",
+					`Cloud Code Assist schema forbids ${key}`,
+					key,
+					node[key],
+				),
+			);
+		}
+	}
+
+	return violations;
+}
+
+function validateCloudCodeAssistSchema(schema: unknown): SchemaCompatibilityViolation[] {
+	if (isValidJsonSchema(schema)) {
+		return [];
+	}
+	return [
+		createViolation(
+			"root",
+			"cca-meta-schema-validation",
+			"Cloud Code Assist schema is not a structurally valid JSON Schema",
+		),
+	];
+}
+
+export function validateSchemaCompatibility(
+	schema: unknown,
+	provider: SchemaCompatibilityProvider,
+): SchemaCompatibilityResult {
+	const violations: SchemaCompatibilityViolation[] = [];
+
+	switch (provider) {
+		case "openai-strict": {
+			walkSchema(schema, { path: "root" }, (node, state) => {
+				violations.push(...validateStrictNode(node, state));
+			});
+			break;
+		}
+		case "google": {
+			walkSchema(schema, { path: "root" }, (node, state) => {
+				violations.push(...validateGoogleNode(node, state));
+			});
+			break;
+		}
+		case "cloud-code-assist-claude": {
+			walkSchema(schema, { path: "root" }, (node, state) => {
+				violations.push(...validateCloudCodeAssistNode(node, state));
+			});
+			violations.push(...validateCloudCodeAssistSchema(schema));
+			break;
+		}
+	}
+
+	return {
+		provider,
+		compatible: violations.length === 0,
+		violations,
+	};
+}
+
+export function validateStrictSchemaEnforcement(
+	originalSchema: Record<string, unknown>,
+	result: StrictSchemaEnforcementResult,
+): SchemaCompatibilityResult {
+	if (result.strict) {
+		return validateSchemaCompatibility(result.schema, "openai-strict");
+	}
+
+	const violations: SchemaCompatibilityViolation[] = [];
+	if (result.schema !== originalSchema) {
+		violations.push(
+			createViolation(
+				"root",
+				"strict-fail-open-original-schema",
+				"Strict fail-open must return the original schema object when strict=false",
+			),
+		);
+	}
+
+	return {
+		provider: "openai-strict",
+		compatible: violations.length === 0,
+		violations,
+	};
+}