@server-driven-impact/cache-contract 0.5.0-cache-contract.2

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @server-driven-impact/cache-contract
+
+## 0.4.1
+
+- Add versioned cache contracts, query-key construction, OpenAPI metadata, and ImpactSet conversion.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Woohyun Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,55 @@
+# @server-driven-impact/cache-contract
+
+[English](./README.md) | [한국어](./README.ko.md)
+
+SDI endpoint, OpenAPI operation, 정규화 입력, 캐시 키의 관계를 버전된 계약으로 정의합니다. 브라우저 캐시를 조회하지 않고 `ImpactSet`을 데이터 전용 무효화 지시로 변환합니다.
+
+```ts
+import { buildQueryKey, defineCacheContract } from '@server-driven-impact/cache-contract';
+
+const contract = defineCacheContract({
+  id: 'company-api', version: 1,
+  queries: [{
+    operationId: 'getOrder', endpoint: 'orders.detail', kind: 'query',
+    input: {id: {type: 'string', required: true, exclude: ['list']}},
+    key: {prefix: ['orders'], path: ['id']}, fallback: ['orders'],
+  }],
+});
+
+buildQueryKey(contract, 'getOrder', {id: 'one'}); // ['orders', 'one']
+```
+
+`cacheContractOpenApiExtension(contract)`의 결과를 루트 `x-sdi-cache` 확장 값으로 사용합니다. 생성 클라이언트는 mutation 요청에 `{id, version}`을 전달합니다. 서버의 `createCacheContractRegistry()`는 지원하지 않는 버전을 거절하며 `compileCacheInvalidations()`는 `{contractId, contractVersion, scope, invalidations}`를 만듭니다.
+
+결과에 영향을 주는 identity 입력은 모두 선언하고 키에 포함해야 합니다. 선언하지 않은 입력은 버리지 않고 거절합니다. 기존 `prefix/path/params`와 중첩 선언형 template을 지원합니다. `fallback`은 생성되는 모든 키를 포함하는 TanStack 부분 키여야 하며 등록 시 검증합니다. query/infinite 키가 충돌할 가능성이 있으면 거절합니다.
+
+`['orders', 'list', params]` 같은 키에서는 params 객체가 존재할 때 특정 필드가 반드시 있다는 입력 검증이 있을 때만 `paramsAnchor`를 지정합니다. 이 증명이 있으면 protocol-1의 missing-field 의미를 좁은 부분 키로 보존할 수 있고, 없으면 변환기는 안전하게 `fallback`으로 넓힙니다.
+
+## 중첩 키와 입력
+
+`key: {template: ...}`에 `literal`, `input`, `inputs`, `array`, `object` 노드를 조합합니다. oRPC 의존성이나 앱별 compiler 없이 기존 `[path, {input, type:'query'}]` 키를 표현할 수 있습니다. 실제 코드 예제는 [영문 README](./README.md#nested-keys-and-inputs), 전환 절차는 [통합 가이드](../../docs/migrations/cache-contract-0.5.md)에 있습니다.
+
+- 배열: `{type:'array',items:...,order:'preserve'|'set'}`. 기본은 순서·중복 보존입니다. 명시적 `set`만 canonical JSON 기준 정렬·중복 제거를 합니다.
+- 객체: `{type:'object',properties:...}`. 중첩 필드도 모두 선언하며 알 수 없는 필드는 거절합니다.
+- 생략된 optional 필드는 없습니다. `default`를 선언한 경우에만 채웁니다. `null`은 `nullable:true`로 허용하며 생략과 구별합니다.
+- 날짜는 timezone이 명시된 값만 받아 UTC ISO로 바꿉니다. `format:'uuid'`는 검증 후 소문자로 바꿉니다.
+
+`prepareCacheQuery(contract, operationId, input)`의 `input`을 API에 전달하고 `queryKey`를 캐시에 사용하십시오. `normalizeCacheInput`도 제공합니다. 키만 정규화해서 요청 의미와 어긋나게 해서는 안 됩니다. 기존 키 유지가 목적이면 기존 API와 같은 정규화 정책을 선택합니다.
+
+Infinite query는 `type:'infinite'` 같은 별도 literal로 구분합니다. `input`은 목록 identity, `pageInput`은 실행 전용 cursor/page 필드입니다. `buildQueryExecutionInput(contract, operationId, identity, page)`는 정규화한 실행 입력을 합칩니다. `buildQueryKey`는 page 전용 필드를 거절하며 모든 페이지가 목록 키 하나를 공유합니다.
+
+## 누락 검증과 정밀도
+
+`validateCacheContractCoverage(contract, [{endpoint, cache:'cacheable'|'no-store'}])`로 생성·시작 단계에 검증합니다. Runtime은 등록된 **각 계약**에 자동 적용합니다. 모든 endpoint는 query 또는 `excludedEndpoints:[{endpoint,reason:'no-store'|'not-consumed'}]`로 명시해야 합니다. no-store 조회에는 재사용 키를 등록할 수 없습니다. 계약에 없는 impact endpoint는 `CACHE_ENDPOINT_UNCOVERED` 오류이며 명시적으로 제외한 경우에만 생략합니다.
+
+`compileCacheInvalidations`의 네 번째 인자 또는 runtime의 `cacheInvalidationOptions`에 `{explain, maxInvalidations, maxBytes}`를 전달합니다. 진단에는 endpoint/operation, selector 필드명, 확대 이유와 필터 수만 포함하며 사용자 값은 넣지 않습니다. 실제 범위는 반환된 filters와 함께 확인합니다. callback이 던진 오류도 커밋 후 실패로 처리되므로 로깅 callback은 예외를 던지지 않아야 합니다.
+
+주요 확대 이유는 `missing-field`, `comparison-unproven`, `page-input`, `input-unrepresentable`, `endpoint-policy`, `budget`입니다. Protocol 1은 생략 필드와 보수적 DB equality까지 매칭합니다. 따라서 unrestricted string은 대소문자/후행 공백 때문에 `required:true`만으로 정밀 변환하지 않습니다. 숫자·boolean·정규화된 UUID 또는 일치 값이 하나인 유한 `enum`처럼 비교를 증명할 수 있어야 합니다. optional/default 필드는 보통 fallback으로 넓어집니다.
+
+Runtime은 필수·비-coerce 문자열에서 입력 필드가 그대로 전달되고, 직접 Query equality binding과 실제 컬럼의 exact 비교에 대한 adapter 검증이 모두 있으면 자동으로 정밀화합니다. Runtime은 매 요청에서 parser 전후 값을 검사합니다. 독립 `compileCacheInvalidations()`는 runtime/DB 증명이 없으므로 보수적인 동작을 유지합니다. DB 비교가 미지원이거나 검증 전이면 `comparison-unproven`으로 확대합니다.
+
+`paramsAnchor:['id']`는 `{page:2}`를 유효 입력으로 받지 않는 경우에만 사용합니다. 키 준비 함수가 이를 검사하지만, 기존 외부 캐시까지 보증하지는 않습니다. 잘못된 기존 키는 먼저 지우거나 이전해야 합니다. anchor가 있어도 optional page selector나 증명할 수 없는 문자열 비교는 넓힙니다.
+
+Endpoint 대신 domain 단위 fallback도 지정할 수 있습니다. 예: `[['data','profile']]`. `invalidation:'endpoint'`는 항상 fallback을 선택합니다. 예산 초과 시 지시를 자르지 않고 넓히며, 최소 안전 지시도 담지 못하면 오류로 알립니다.
+
+배열·객체 **키 표현**을 지원하는 것이 ImpactSet v1의 IN/range/중첩 selector 추론을 추가한다는 뜻은 아닙니다. 해당 정밀도는 후속 범위이며 현재는 안전한 fallback을 유지합니다.

package/README.md

@@ -0,0 +1,72 @@
+# @server-driven-impact/cache-contract
+
+[English](./README.md) | [한국어](./README.ko.md)
+
+Defines a versioned relationship between SDI endpoints, OpenAPI operations, normalized inputs, and cache keys. It converts an `ImpactSet` into data-only invalidation instructions; it does not inspect a browser cache.
+
+```ts
+import { buildQueryKey, defineCacheContract } from '@server-driven-impact/cache-contract';
+
+const contract = defineCacheContract({
+  id: 'company-api', version: 1,
+  queries: [{
+    operationId: 'getOrder', endpoint: 'orders.detail', kind: 'query',
+    input: {id: {type: 'string', required: true, exclude: ['list']}},
+    key: {prefix: ['orders'], path: ['id']}, fallback: ['orders'],
+  }],
+});
+
+buildQueryKey(contract, 'getOrder', {id: 'one'}); // ['orders', 'one']
+```
+
+Use `cacheContractOpenApiExtension(contract)` as the value of a root-level `x-sdi-cache` extension. Generated clients send `{id, version}` with mutations. On the server, `createCacheContractRegistry()` rejects unsupported versions and `compileCacheInvalidations()` returns `{contractId, contractVersion, scope, invalidations}`.
+
+Every result-affecting identity input must be declared and represented in the key. Unknown input fields are rejected, not dropped. Flat `prefix/path/params` and recursive declarative templates are supported. `fallback` must be a TanStack partial key proven to cover every generated key. Potentially colliding query/infinite templates are rejected.
+
+For a key such as `['orders', 'list', params]`, use `paramsAnchor` only when input validation guarantees those fields whenever the params object exists. This proof lets protocol-1 missing-field matching preserve a narrow partial key; otherwise conversion safely widens to `fallback`.
+
+## Nested keys and inputs
+
+No oRPC dependency or application-specific compiler is needed for its key shape:
+
+```ts
+const rpc = defineCacheContract({
+  id: 'rpc', version: 1,
+  queries: [{
+    operationId: 'profile', endpoint: 'profile.read', kind: 'query',
+    input: {userId: {type: 'string', required: true}},
+    key: {template: {kind: 'array', items: [
+      {kind: 'literal', value: ['data', 'profile', 'read']},
+      {kind: 'object', fields: {
+        input: {kind: 'inputs'},
+        type: {kind: 'literal', value: 'query'},
+      }},
+    ]}},
+    fallback: [['data', 'profile', 'read'], {type: 'query'}],
+  }],
+});
+// [['data', 'profile', 'read'], {input: {userId: 'user-a'}, type: 'query'}]
+buildQueryKey(rpc, 'profile', {userId: 'user-a'});
+```
+
+Nodes are `literal`, `input` (one top-level field, including a structured value), `inputs` (all or named fields), `object`, and `array`. An omitted optional object field is absent; null remains null. Use `inputs.omitEmpty` when an empty input object should be absent. Optional array elements must not shift positions.
+
+Recursive fields use `{type:'array', items:..., order:'preserve'|'set'}` and `{type:'object', properties:...}`. Arrays preserve order and duplicates by default; explicit `set` deduplicates and sorts by canonical JSON. Object property ordering does not affect identity; unknown nested fields are rejected. Optional fields stay absent unless a default is declared; null requires `nullable:true`. Dates require an explicit timezone and become ISO UTC. `format:'uuid'` validates and lowercases strings.
+
+Use `prepareCacheQuery(contract, operationId, input)` and send its **input** to the API while using its **queryKey**. `normalizeCacheInput` is also exported. Do not normalize only the key when the request's meaning would differ. Preserving existing keys requires choosing normalization that matches the existing API.
+
+Infinite operations use a separate literal such as `type:'infinite'` and may declare `pageInput` alongside identity `input`. `buildQueryExecutionInput(contract, operationId, identity, page)` merges both normalized inputs for the request; `buildQueryKey` rejects page-only fields. All pages share the infinite query key. Page fields in an impact widen to fallback.
+
+## Coverage and diagnostics
+
+`validateCacheContractCoverage(contract, [{endpoint, cache:'cacheable'|'no-store'}])` validates an inventory at startup/generation. The runtime does this automatically for **each** configured contract. Every endpoint must have a query or an explicit `excludedEndpoints: [{endpoint, reason:'no-store'|'not-consumed'}]` entry. No-store reads cannot receive reusable keys. Unknown impact endpoints throw `CACHE_ENDPOINT_UNCOVERED`; explicit exclusions alone may produce no instructions.
+
+Pass `{explain(diagnostic), maxInvalidations, maxBytes}` to `compileCacheInvalidations`, or `cacheInvalidationOptions` to the runtime. Diagnostics contain endpoint/operation, selector field names, reason, and filter count—not user values. Reasons include `missing-field`, `comparison-unproven`, `page-input`, `input-unrepresentable`, `endpoint-policy`, and `budget`. Compare these with the returned filters when debugging; do not log raw keys in production. An explain callback must not throw; failures remain explicit post-commit errors.
+
+Protocol 1 matches absent fields and conservatively handles database equality. Unrestricted strings can match different case/trailing-space keys, so precise conversion requires a proven domain (numbers, booleans, normalized UUIDs, or a finite `enum` with one matching value). A mere `required:true` string is not sufficient. Optional/defaulted fields generally widen. `invalidation:'endpoint'` deliberately always uses fallback. A domain prefix such as `[['data','profile']]` may be used as fallback if it covers every operation key.
+
+The runtime automatically refines required, non-coerced string inputs when it has an unchanged input field, a direct Query equality binding, and adapter validation of the live column's exact comparison semantics. Runtime enforces the unchanged input on every request. Standalone `compileCacheInvalidations()` remains conservative because it has no runtime/database proof. Unsupported or unvalidated comparison reports `comparison-unproven`.
+
+`paramsAnchor:['id']` is appropriate for `['orders','list',{id,page?}]` only if `{page:2}` is invalid. Key preparation enforces this. Declaring an anchor that older cached requests do not honor is unsafe: clear/migrate them first. Selecting optional `page` still widens even with an ID anchor. Anchors do not prove string comparison semantics.
+
+Structured **key identity** does not add IN/range/nested selector inference to ImpactSet v1. Unsupported precision widens safely; it never silently removes an endpoint or truncates instructions. If even broad instructions exceed the budget, compilation throws.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { type ImpactSet, type Scalar } from '@server-driven-impact/core';
+import type { CacheCompileOptions, CacheContract, CacheContractReference, CacheEndpoint, CacheInvalidationSet, CacheValue, QueryKey, StringComparisonStatus } from './types.js';
+export type * from './types.js';
+export { isCacheValue } from './input.js';
+export declare const CACHE_LIMITS: Readonly<{
+    contracts: 32;
+    queries: 512;
+    invalidations: 512;
+    contractBytes: 1048576;
+    responseBytes: 131072;
+}>;
+export declare function defineCacheContract<const T extends CacheContract>(contract: T): T;
+/** Inventory is supplied by a runtime or SDK generator, not inferred from impacts. */
+export declare function validateCacheContractCoverage(candidate: CacheContract, endpoints: readonly CacheEndpoint[]): void;
+export declare function normalizeCacheInput(contract: CacheContract, operationId: string, input: Record<string, unknown>): Record<string, CacheValue>;
+/** Send this normalized input to the API as well as using its queryKey. */
+export declare function prepareCacheQuery(contract: CacheContract, operationId: string, input: Record<string, unknown>): {
+    input: Record<string, CacheValue>;
+    queryKey: QueryKey;
+};
+export declare function buildQueryKey(contract: CacheContract, operationId: string, input: Record<string, unknown>): QueryKey;
+export declare function buildQueryExecutionInput(contract: CacheContract, operationId: string, input: Record<string, unknown>, pageInput: Record<string, unknown>): Record<string, CacheValue>;
+type StringComparison = (endpoint: string, input: string) => StringComparisonStatus;
+export declare function validateCacheCompileOptions(options: CacheCompileOptions): void;
+export declare function compileCacheInvalidations(candidate: CacheContract, impact: ImpactSet, scope: Scalar, options?: CacheCompileOptions): CacheInvalidationSet;
+export declare function cacheContractOpenApiExtension(candidate: CacheContract): Readonly<Record<string, unknown>>;
+export interface CacheContractRegistry {
+    resolve(reference: CacheContractReference): CacheContract;
+    compile(reference: CacheContractReference, impact: ImpactSet, scope: Scalar): CacheInvalidationSet;
+}
+export declare function createCacheContractRegistry(contracts: readonly CacheContract[], options?: {
+    endpoints?: readonly CacheEndpoint[];
+    compile?: CacheCompileOptions;
+    /** Runtime-owned evidence. Ordinary consumers should use compileCacheInvalidations. */
+    stringComparison?: StringComparison;
+}): CacheContractRegistry;

package/dist/index.js

@@ -0,0 +1,262 @@
+// @ts-self-types="./index.d.ts"
+import { byteLength, canonical, isScalar, LIMITS } from '@server-driven-impact/core';
+import { isCacheValue, isRecord, normalizeFields, own, selectorValue, validateFields } from './input.js';
+import { renderKey, validateFallback, validateKeySeparation, validateTemplate } from './template.js';
+export { isCacheValue } from './input.js';
+export const CACHE_LIMITS = Object.freeze({ contracts: 32, queries: 512, invalidations: 512, contractBytes: 1_048_576, responseBytes: 131_072 });
+const validated = new WeakSet();
+function deepFreeze(value) {
+    if (value && typeof value === 'object') {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function name(value, code) {
+    if (typeof value !== 'string' || !value.length)
+        throw new Error(code);
+}
+export function defineCacheContract(contract) {
+    if (validated.has(contract))
+        return contract;
+    if (!isCacheValue(contract))
+        throw new Error('INVALID_CACHE_CONTRACT_JSON');
+    name(contract.id, 'INVALID_CACHE_CONTRACT_ID');
+    if (!Number.isSafeInteger(contract.version) || contract.version < 1)
+        throw new Error('INVALID_CACHE_CONTRACT_VERSION');
+    if (!Array.isArray(contract.queries))
+        throw new Error('CACHE_QUERIES_REQUIRED');
+    if (contract.queries.length > CACHE_LIMITS.queries)
+        throw new Error('CACHE_QUERY_LIMIT');
+    if (byteLength(contract) > CACHE_LIMITS.contractBytes)
+        throw new Error('CACHE_CONTRACT_BYTE_LIMIT');
+    const snapshot = structuredClone(contract);
+    const operations = new Set();
+    for (const query of snapshot.queries) {
+        name(query.operationId, 'INVALID_CACHE_OPERATION_ID');
+        name(query.endpoint, 'INVALID_CACHE_ENDPOINT');
+        if (operations.has(query.operationId))
+            throw new Error('DUPLICATE_CACHE_OPERATION:' + query.operationId);
+        operations.add(query.operationId);
+        if (!['query', 'infinite'].includes(query.kind))
+            throw new Error('INVALID_CACHE_QUERY_KIND');
+        if (query.invalidation !== undefined && !['preserve', 'endpoint'].includes(query.invalidation))
+            throw new Error('INVALID_CACHE_INVALIDATION_POLICY');
+        validateFields(query.input);
+        if (query.pageInput) {
+            if (query.kind !== 'infinite')
+                throw new Error('CACHE_PAGE_INPUT_REQUIRES_INFINITE');
+            validateFields(query.pageInput);
+            if (Object.keys(query.pageInput).some(field => own(query.input, field)))
+                throw new Error('CACHE_PAGE_INPUT_OVERLAP');
+        }
+        validateTemplate(query);
+        validateFallback(query);
+    }
+    validateKeySeparation(snapshot.queries);
+    const excluded = new Set();
+    if (snapshot.excludedEndpoints !== undefined && !Array.isArray(snapshot.excludedEndpoints))
+        throw new Error('INVALID_CACHE_EXCLUSIONS');
+    for (const entry of snapshot.excludedEndpoints ?? []) {
+        name(entry.endpoint, 'INVALID_CACHE_ENDPOINT');
+        if (!['no-store', 'not-consumed'].includes(entry.reason))
+            throw new Error('INVALID_CACHE_EXCLUSION_REASON');
+        if (excluded.has(entry.endpoint) || snapshot.queries.some(query => query.endpoint === entry.endpoint))
+            throw new Error('DUPLICATE_CACHE_ENDPOINT_POLICY:' + entry.endpoint);
+        excluded.add(entry.endpoint);
+    }
+    validated.add(snapshot);
+    return deepFreeze(snapshot);
+}
+/** Inventory is supplied by a runtime or SDK generator, not inferred from impacts. */
+export function validateCacheContractCoverage(candidate, endpoints) {
+    const contract = defineCacheContract(candidate);
+    const inventory = new Map();
+    for (const endpoint of endpoints) {
+        name(endpoint.endpoint, 'INVALID_CACHE_ENDPOINT');
+        if (!['cacheable', 'no-store'].includes(endpoint.cache))
+            throw new Error('INVALID_CACHE_ENDPOINT_POLICY');
+        if (inventory.has(endpoint.endpoint))
+            throw new Error('DUPLICATE_CACHE_INVENTORY_ENDPOINT:' + endpoint.endpoint);
+        inventory.set(endpoint.endpoint, endpoint);
+        const excluded = contract.excludedEndpoints?.find(entry => entry.endpoint === endpoint.endpoint);
+        const registered = contract.queries.some(query => query.endpoint === endpoint.endpoint);
+        if (!excluded && !registered)
+            throw new Error('CACHE_ENDPOINT_UNCOVERED:' + endpoint.endpoint);
+        if (endpoint.cache === 'no-store' && registered)
+            throw new Error('CACHE_ENDPOINT_REQUIRES_NO_STORE:' + endpoint.endpoint);
+        if (endpoint.cache === 'cacheable' && excluded?.reason === 'no-store')
+            throw new Error('CACHE_ENDPOINT_NOT_NO_STORE:' + endpoint.endpoint);
+    }
+    for (const entry of [...contract.queries, ...contract.excludedEndpoints ?? []]) {
+        if (!inventory.has(entry.endpoint))
+            throw new Error('CACHE_ENDPOINT_NOT_REGISTERED:' + entry.endpoint);
+    }
+}
+function operation(contract, operationId) {
+    const query = defineCacheContract(contract).queries.find(candidate => candidate.operationId === operationId);
+    if (!query)
+        throw new Error('UNKNOWN_CACHE_OPERATION:' + operationId);
+    return query;
+}
+function normalize(query, input) {
+    const normalized = normalizeFields(query.input, input);
+    if (!('template' in query.key)) {
+        const params = query.key.params?.filter(field => own(normalized, field)) ?? [];
+        if (params.length && query.key.paramsAnchor?.some(field => !own(normalized, field)))
+            throw new Error('CACHE_PARAMS_ANCHOR_REQUIRED');
+    }
+    return normalized;
+}
+export function normalizeCacheInput(contract, operationId, input) {
+    return normalize(operation(contract, operationId), input);
+}
+/** Send this normalized input to the API as well as using its queryKey. */
+export function prepareCacheQuery(contract, operationId, input) {
+    const query = operation(contract, operationId);
+    const normalized = normalize(query, input);
+    return { input: normalized, queryKey: renderKey(query, normalized).queryKey };
+}
+export function buildQueryKey(contract, operationId, input) {
+    return prepareCacheQuery(contract, operationId, input).queryKey;
+}
+export function buildQueryExecutionInput(contract, operationId, input, pageInput) {
+    const query = operation(contract, operationId);
+    if (query.kind !== 'infinite')
+        throw new Error('CACHE_PAGE_INPUT_REQUIRES_INFINITE');
+    return { ...normalize(query, input), ...normalizeFields(query.pageInput ?? {}, pageInput, 'pageInput') };
+}
+function broad(query, reason) {
+    return { filters: [{ queryKey: query.fallback, exact: false }], reason };
+}
+function forValue(query, value, stringComparison) {
+    const known = Object.create(null);
+    const flat = 'template' in query.key ? undefined : query.key;
+    const anchors = flat?.paramsAnchor ?? [];
+    for (const [field, expected] of Object.entries(value)) {
+        if (query.pageInput && own(query.pageInput, field))
+            return broad(query, 'page-input');
+        if (!own(query.input, field))
+            return broad(query, 'input-unrepresentable');
+        const definition = query.input[field];
+        // A default can hide an omitted field, which protocol 1 must also match.
+        if (own(definition, 'default') || (!definition.required && !anchors.includes(field)))
+            return broad(query, 'missing-field');
+        const stringStatus = definition.type === 'string' && definition.required && !definition.coerce && definition.format !== 'uuid'
+            ? stringComparison?.(query.endpoint, field) : undefined;
+        const normalized = selectorValue(definition, expected, stringStatus === 'verified');
+        if (normalized === undefined)
+            return broad(query, 'comparison-unproven');
+        known[field] = normalized;
+    }
+    if (flat) {
+        if ((flat.path ?? []).some(field => !own(known, field)))
+            return broad(query, 'missing-field');
+        const base = [...flat.prefix, ...(flat.path ?? []).map(field => known[field])];
+        const selectedParams = (flat.params ?? []).filter(field => own(known, field));
+        if (!selectedParams.length)
+            return { filters: [{ queryKey: base, exact: !flat.params }], reason: 'precise' };
+        if (selectedParams.some(field => !query.input[field].required)) {
+            if (!anchors.length || !anchors.every(field => own(known, field)))
+                return broad(query, 'missing-field');
+            return { filters: [
+                    { queryKey: flat.omitEmptyParams ? base : [...base, {}], exact: true },
+                    { queryKey: [...base, Object.fromEntries(selectedParams.map(field => [field, known[field]]))], exact: false },
+                ], reason: 'precise' };
+        }
+    }
+    return { filters: [renderKey(query, known, true)], reason: 'precise' };
+}
+export function validateCacheCompileOptions(options) {
+    for (const [value, maximum] of [[options.maxInvalidations, CACHE_LIMITS.invalidations], [options.maxBytes, CACHE_LIMITS.responseBytes]]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1 || value > maximum))
+            throw new Error('INVALID_CACHE_COMPILE_LIMIT');
+    }
+    if (options.explain !== undefined && typeof options.explain !== 'function')
+        throw new Error('INVALID_CACHE_EXPLAIN');
+}
+function compile(candidate, impact, scope, options, stringComparison) {
+    const contract = defineCacheContract(candidate);
+    validateCacheCompileOptions(options);
+    if (!isScalar(scope))
+        throw new Error('INVALID_CACHE_SCOPE');
+    if (!impact || impact.protocolVersion !== 1)
+        throw new Error('UNSUPPORTED_IMPACT_VERSION');
+    if (!Array.isArray(impact.targets) || impact.targets.length > LIMITS.endpoints)
+        throw new Error('INVALID_IMPACT_TARGETS');
+    const invalidations = [];
+    const affected = new Set();
+    for (const target of impact.targets) {
+        if (!target || typeof target.endpoint !== 'string' || !['caller', 'global'].includes(target.scope))
+            throw new Error('INVALID_IMPACT_TARGET');
+        const queries = contract.queries.filter(query => query.endpoint === target.endpoint);
+        if (!queries.length) {
+            if (!contract.excludedEndpoints?.some(entry => entry.endpoint === target.endpoint))
+                throw new Error('CACHE_ENDPOINT_UNCOVERED:' + target.endpoint);
+            options.explain?.({ endpoint: target.endpoint, reason: 'excluded', filterCount: 0 });
+            continue;
+        }
+        const selector = target.selector;
+        // Mirror protocol-1's fail-open selector matching, never silently drop it.
+        const values = selector?.kind === 'inputs' && Array.isArray(selector.values) && selector.values.length > 0 &&
+            selector.values.length <= LIMITS.selectors && selector.values.every(value => isRecord(value) && Object.values(value).every(isScalar))
+            ? selector.values : undefined;
+        for (const query of queries) {
+            affected.add(query);
+            const decisions = query.invalidation === 'endpoint' ? [broad(query, 'endpoint-policy')]
+                : values ? values.map(value => forValue(query, value, stringComparison)) : [broad(query, 'all')];
+            for (const decision of decisions) {
+                invalidations.push(...decision.filters);
+                options.explain?.({ endpoint: query.endpoint, operationId: query.operationId, reason: decision.reason,
+                    selectorKind: values ? 'inputs' : 'all', selectorFields: values ? [...new Set(values.flatMap(Object.keys))].sort() : [],
+                    filterCount: decision.filters.length });
+            }
+        }
+    }
+    const unique = (values) => [...new Map(values.map(value => [value.exact + ':' + canonical(value.queryKey), value])).values()];
+    const payload = (values) => ({ protocolVersion: 1, contractId: contract.id, contractVersion: contract.version, scope, invalidations: unique(values) });
+    const fits = (value) => value.invalidations.length <= (options.maxInvalidations ?? CACHE_LIMITS.invalidations) && byteLength(value) <= (options.maxBytes ?? CACHE_LIMITS.responseBytes);
+    let result = payload(invalidations);
+    if (!fits(result)) {
+        result = payload([...affected].flatMap(query => {
+            options.explain?.({ endpoint: query.endpoint, operationId: query.operationId, reason: 'budget', filterCount: 1 });
+            return broad(query, 'budget').filters;
+        }));
+    }
+    if (!fits(result))
+        throw new Error('CACHE_INVALIDATION_LIMIT');
+    return deepFreeze(result);
+}
+export function compileCacheInvalidations(candidate, impact, scope, options = {}) {
+    return compile(candidate, impact, scope, options);
+}
+export function cacheContractOpenApiExtension(candidate) {
+    const contract = defineCacheContract(candidate);
+    return deepFreeze({ contractId: contract.id, contractVersion: contract.version, queries: contract.queries, excludedEndpoints: contract.excludedEndpoints ?? [] });
+}
+export function createCacheContractRegistry(contracts, options = {}) {
+    if (contracts.length > CACHE_LIMITS.contracts)
+        throw new Error('CACHE_CONTRACT_LIMIT');
+    const compileOptions = { ...options.compile };
+    validateCacheCompileOptions(compileOptions);
+    const entries = new Map();
+    for (const candidate of contracts) {
+        const contract = defineCacheContract(candidate);
+        if (options.endpoints)
+            validateCacheContractCoverage(contract, options.endpoints);
+        const key = contract.id + ':' + contract.version;
+        if (entries.has(key))
+            throw new Error('DUPLICATE_CACHE_CONTRACT:' + key);
+        entries.set(key, contract);
+    }
+    const resolve = (reference) => {
+        const contract = entries.get(reference.id + ':' + reference.version);
+        if (!contract)
+            throw new Error('UNSUPPORTED_CACHE_CONTRACT:' + reference.id + ':' + reference.version);
+        return contract;
+    };
+    return Object.freeze({ resolve, compile(reference, impact, scope) {
+            return compile(resolve(reference), impact, scope, compileOptions, options.stringComparison);
+        } });
+}

package/dist/input.d.ts

@@ -0,0 +1,12 @@
+import { type Scalar } from '@server-driven-impact/core';
+import type { CacheInputField, CacheValue } from './types.js';
+export declare const own: (value: object, name: string) => boolean;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/** Bounded JSON validation, including sparse arrays and cyclic/non-JSON input. */
+export declare function isCacheValue(value: unknown, depth?: number): value is CacheValue;
+export declare const OMIT: unique symbol;
+export declare function normalizeField(field: CacheInputField, value: unknown, path: string): CacheValue | typeof OMIT;
+export declare function normalizeFields(fields: Readonly<Record<string, CacheInputField>>, value: unknown, path?: string): Record<string, CacheValue>;
+export declare function validateFields(fields: Readonly<Record<string, CacheInputField>>, depth?: number): void;
+/** A sufficient proof relative to the existing conservative protocol-1 matcher. */
+export declare function selectorValue(field: CacheInputField, expected: Scalar, verifiedExactString?: boolean): CacheValue | undefined;

package/dist/input.js

@@ -0,0 +1,170 @@
+// @ts-self-types="./input.d.ts"
+import { canonical, isScalar, matchesInputSelector } from '@server-driven-impact/core';
+export const own = (value, name) => Object.hasOwn(value, name);
+export const isRecord = (value) => value !== null && typeof value === 'object' &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+/** Bounded JSON validation, including sparse arrays and cyclic/non-JSON input. */
+export function isCacheValue(value, depth = 0) {
+    if (depth > 32)
+        return false;
+    if (isScalar(value))
+        return true;
+    if (Array.isArray(value))
+        return Array.from(value).every(item => isCacheValue(item, depth + 1));
+    return isRecord(value) && Object.values(value).every(item => isCacheValue(item, depth + 1));
+}
+export const OMIT = Symbol('omitted');
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export function normalizeField(field, value, path) {
+    if (value === undefined) {
+        if (own(field, 'default'))
+            value = field.default;
+        else if (!field.required)
+            return OMIT;
+        else
+            throw new Error('CACHE_INPUT_REQUIRED:' + path);
+    }
+    if (value === null) {
+        if (!field.nullable)
+            throw new Error('CACHE_INPUT_NULL:' + path);
+        if ('enum' in field && field.enum && !field.enum.includes(null))
+            throw new Error('CACHE_INPUT_ENUM:' + path);
+        if ('exclude' in field && field.exclude?.includes(null))
+            throw new Error('CACHE_INPUT_EXCLUDED:' + path);
+        return null;
+    }
+    if (field.type === 'array') {
+        if (!Array.isArray(value))
+            throw new Error('INVALID_CACHE_INPUT:' + path);
+        const items = Array.from(value).map(item => {
+            const normalized = normalizeField(field.items, item, path + '[]');
+            if (normalized === OMIT)
+                throw new Error('CACHE_ARRAY_ITEM_REQUIRED:' + path);
+            return normalized;
+        });
+        if (field.order !== 'set')
+            return items;
+        return [...new Map(items.map(item => [canonical(item), item])).entries()]
+            .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, item]) => item);
+    }
+    if (field.type === 'object')
+        return normalizeFields(field.properties, value, path);
+    let result;
+    if (field.type === 'date-time') {
+        // Require an explicit timezone; local-time parsing would differ across hosts.
+        if (!(value instanceof Date) && (typeof value !== 'string' || !/T.*(?:Z|[+-]\d{2}:\d{2})$/i.test(value))) {
+            throw new Error('CACHE_DATE_TIMEZONE_REQUIRED:' + path);
+        }
+        const date = value instanceof Date ? value : new Date(value);
+        if (!Number.isFinite(date.valueOf()))
+            throw new Error('INVALID_CACHE_INPUT:' + path);
+        result = date.toISOString();
+    }
+    else if (typeof value === field.type && isScalar(value))
+        result = value;
+    else if (field.coerce && field.type === 'number' && typeof value === 'string' && value.trim() && Number.isFinite(Number(value)))
+        result = Number(value);
+    else if (field.coerce && field.type === 'string' && (typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))))
+        result = String(value);
+    else if (field.coerce && field.type === 'boolean' && (value === 'true' || value === 'false'))
+        result = value === 'true';
+    else
+        throw new Error('INVALID_CACHE_INPUT:' + path);
+    if (field.format === 'uuid') {
+        if (typeof result !== 'string' || !uuid.test(result))
+            throw new Error('INVALID_CACHE_UUID:' + path);
+        result = result.toLowerCase();
+    }
+    if (field.exclude?.some(item => canonical(item) === canonical(result)))
+        throw new Error('CACHE_INPUT_EXCLUDED:' + path);
+    if (field.enum && !field.enum.some(item => canonical(item) === canonical(result)))
+        throw new Error('CACHE_INPUT_ENUM:' + path);
+    return result;
+}
+export function normalizeFields(fields, value, path = 'input') {
+    if (!isRecord(value))
+        throw new Error('INVALID_CACHE_INPUT:' + path);
+    for (const name of Object.keys(value))
+        if (!own(fields, name))
+            throw new Error('UNKNOWN_CACHE_INPUT:' + path + '.' + name);
+    return Object.fromEntries(Object.entries(fields).flatMap(([name, field]) => {
+        const normalized = normalizeField(field, own(value, name) ? value[name] : undefined, path + '.' + name);
+        return normalized === OMIT ? [] : [[name, normalized]];
+    }));
+}
+export function validateFields(fields, depth = 0) {
+    if (!isRecord(fields) || depth > 24)
+        throw new Error('INVALID_CACHE_INPUT_SCHEMA');
+    for (const [name, field] of Object.entries(fields)) {
+        if (!name || !isRecord(field))
+            throw new Error('INVALID_CACHE_INPUT_SCHEMA');
+        for (const flag of ['required', 'nullable', 'coerce']) {
+            if (own(field, flag) && typeof field[flag] !== 'boolean')
+                throw new Error('INVALID_CACHE_INPUT_SCHEMA');
+        }
+        if (field.type === 'array') {
+            if (field.order !== undefined && !['preserve', 'set'].includes(field.order))
+                throw new Error('INVALID_CACHE_ARRAY_ORDER');
+            validateFields({ item: field.items }, depth + 1);
+        }
+        else if (field.type === 'object')
+            validateFields(field.properties, depth + 1);
+        else {
+            if (!['string', 'number', 'boolean', 'date-time'].includes(field.type))
+                throw new Error('INVALID_CACHE_INPUT_TYPE');
+            if (field.format !== undefined && (field.type !== 'string' || field.format !== 'uuid'))
+                throw new Error('INVALID_CACHE_INPUT_FORMAT');
+            for (const values of [field.enum, field.exclude])
+                if (values !== undefined) {
+                    if (!Array.isArray(values) || !values.every(isScalar))
+                        throw new Error('INVALID_CACHE_INPUT_DOMAIN');
+                    for (const item of values) {
+                        const normalized = normalizeField({ ...field, enum: undefined, exclude: undefined }, item, name);
+                        if (normalized === OMIT || canonical(normalized) !== canonical(item))
+                            throw new Error('CACHE_INPUT_DOMAIN_NOT_NORMALIZED:' + name);
+                    }
+                }
+            if (field.enum && !field.enum.length)
+                throw new Error('EMPTY_CACHE_INPUT_ENUM');
+        }
+        if (own(field, 'default')) {
+            if (!isCacheValue(field.default))
+                throw new Error('INVALID_CACHE_DEFAULT');
+            normalizeField(field, field.default, name);
+        }
+    }
+}
+/** A sufficient proof relative to the existing conservative protocol-1 matcher. */
+export function selectorValue(field, expected, verifiedExactString = false) {
+    if (field.type === 'array' || field.type === 'object')
+        return undefined;
+    if (verifiedExactString && field.type === 'string' && typeof expected === 'string' && !field.coerce) {
+        if (field.enum && !field.enum.some(value => canonical(value) === canonical(expected)))
+            return undefined;
+        if (field.exclude?.some(value => canonical(value) === canonical(expected)))
+            return undefined;
+        return expected;
+    }
+    if (field.enum) {
+        const matches = field.enum.filter(value => matchesInputSelector({ v: value }, { kind: 'inputs', values: [{ v: expected }] }));
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    if (expected === null)
+        return field.nullable ? null : undefined;
+    if (field.type === 'number') {
+        // Numeric strings in v1 may describe numeric API inputs without coerce enabled.
+        if (typeof expected === 'string' && expected.trim() && Number.isFinite(Number(expected)))
+            return Number(expected);
+        return typeof expected === 'number' ? expected : undefined;
+    }
+    if (field.type === 'boolean') {
+        if (typeof expected === 'boolean')
+            return expected;
+        if (typeof expected === 'string' && /^(true|false)$/i.test(expected))
+            return expected.toLowerCase() === 'true';
+    }
+    if (field.format === 'uuid' && typeof expected === 'string' && uuid.test(expected))
+        return expected.toLowerCase();
+    // Unrestricted strings may match distinct NOCASE/RTRIM/numeric representations.
+    return undefined;
+}

package/dist/template.d.ts

@@ -0,0 +1,9 @@
+import type { CacheKeyNode, CacheQueryContract, CacheValue, QueryKey } from './types.js';
+export declare function queryTemplate(query: CacheQueryContract): CacheKeyNode;
+export declare function validateTemplate(query: CacheQueryContract): void;
+export declare function validateKeySeparation(queries: readonly CacheQueryContract[]): void;
+export declare function validateFallback(query: CacheQueryContract): void;
+export declare function renderKey(query: CacheQueryContract, input: Record<string, CacheValue>, partial?: boolean): {
+    queryKey: QueryKey;
+    exact: boolean;
+};

package/dist/template.js

@@ -0,0 +1,209 @@
+// @ts-self-types="./template.d.ts"
+import { canonical } from '@server-driven-impact/core';
+import { isCacheValue, normalizeField, OMIT, own } from './input.js';
+export function queryTemplate(query) {
+    if ('template' in query.key)
+        return query.key.template;
+    const { prefix, path = [], params, omitEmptyParams } = query.key;
+    return { kind: 'array', items: [
+            ...prefix.map(value => ({ kind: 'literal', value })),
+            ...path.map(field => ({ kind: 'input', field })),
+            ...(params ? [{ kind: 'inputs', fields: params, omitEmpty: omitEmptyParams ?? false }] : []),
+        ] };
+}
+export function validateTemplate(query) {
+    const used = new Set();
+    function field(name) {
+        if (!own(query.input, name))
+            throw new Error('UNKNOWN_CACHE_KEY_INPUT:' + name);
+        used.add(name);
+    }
+    function walk(node, depth, inArray, last) {
+        if (!node || depth > 24)
+            throw new Error('INVALID_CACHE_KEY_TEMPLATE');
+        switch (node.kind) {
+            case 'literal':
+                if (!isCacheValue(node.value))
+                    throw new Error('INVALID_CACHE_KEY_LITERAL');
+                break;
+            case 'input':
+                field(node.field);
+                if (inArray && !query.input[node.field].required && !own(query.input[node.field], 'default')) {
+                    throw new Error('CACHE_ARRAY_INPUT_MUST_BE_REQUIRED:' + node.field);
+                }
+                break;
+            case 'inputs':
+                (node.fields ?? Object.keys(query.input)).forEach(field);
+                if (node.omitEmpty !== undefined && typeof node.omitEmpty !== 'boolean')
+                    throw new Error('INVALID_CACHE_KEY_TEMPLATE');
+                if (inArray && node.omitEmpty && !last)
+                    throw new Error('CACHE_OPTIONAL_ARRAY_ITEM_MUST_BE_LAST');
+                break;
+            case 'object':
+                if (!node.fields || Array.isArray(node.fields))
+                    throw new Error('INVALID_CACHE_KEY_TEMPLATE');
+                for (const child of Object.values(node.fields))
+                    walk(child, depth + 1, false, true);
+                break;
+            case 'array':
+                if (!Array.isArray(node.items))
+                    throw new Error('INVALID_CACHE_KEY_TEMPLATE');
+                node.items.forEach((child, index) => walk(child, depth + 1, true, index === node.items.length - 1));
+                break;
+            default: throw new Error('INVALID_CACHE_KEY_TEMPLATE');
+        }
+    }
+    const template = queryTemplate(query);
+    if (template.kind !== 'array' || !template.items.length)
+        throw new Error('CACHE_KEY_ROOT_MUST_BE_ARRAY');
+    walk(template, 0, false, true);
+    for (const name of Object.keys(query.input))
+        if (!used.has(name))
+            throw new Error('CACHE_INPUT_NOT_IN_KEY:' + name);
+    if (!('template' in query.key)) {
+        const { path = [], params = [], paramsAnchor } = query.key;
+        if (new Set([...path, ...params]).size !== path.length + params.length)
+            throw new Error('DUPLICATE_CACHE_KEY_FIELD');
+        if (paramsAnchor && (!paramsAnchor.length || paramsAnchor.some(name => !params.includes(name))))
+            throw new Error('INVALID_CACHE_PARAMS_ANCHOR');
+    }
+}
+function literalShape(value) {
+    if (Array.isArray(value))
+        return { kind: 'array', items: value.map(literalShape) };
+    if (value && typeof value === 'object')
+        return { kind: 'object', fields: Object.fromEntries(Object.entries(value).map(([k, v]) => [k, literalShape(v)])) };
+    return { kind: 'literal', value };
+}
+function shape(node, query) {
+    switch (node.kind) {
+        case 'literal': return literalShape(node.value);
+        case 'input': {
+            const schema = query.input[node.field];
+            return { kind: 'dynamic', schema, optional: !schema.required && !own(schema, 'default') };
+        }
+        case 'inputs': return {
+            kind: 'object', optional: node.omitEmpty,
+            fields: Object.fromEntries((node.fields ?? Object.keys(query.input)).map(name => [name, shape({ kind: 'input', field: name }, query)])),
+        };
+        case 'object': return { kind: 'object', fields: Object.fromEntries(Object.entries(node.fields).map(([k, v]) => [k, shape(v, query)])) };
+        case 'array': return { kind: 'array', items: node.items.map(child => shape(child, query)) };
+    }
+}
+function dynamicMayEqual(schema, value) {
+    try {
+        const result = normalizeField(schema, value, 'collision');
+        return result !== OMIT && canonical(result) === canonical(value);
+    }
+    catch {
+        return false;
+    }
+}
+function intersects(a, b) {
+    if (a.kind === 'dynamic' || b.kind === 'dynamic') {
+        const dynamic = a.kind === 'dynamic' ? a : b;
+        const other = a.kind === 'dynamic' ? b : a;
+        if (other.kind === 'literal')
+            return dynamicMayEqual(dynamic.schema, other.value);
+        if (other.kind === 'array')
+            return dynamic.schema.type === 'array';
+        if (other.kind === 'object')
+            return dynamic.schema.type === 'object';
+        return true;
+    }
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'literal' && b.kind === 'literal')
+        return canonical(a.value) === canonical(b.value);
+    if (a.kind === 'array' && b.kind === 'array') {
+        const minA = a.items.filter(item => !item.optional).length;
+        const minB = b.items.filter(item => !item.optional).length;
+        if (minA > b.items.length || minB > a.items.length)
+            return false;
+        return a.items.every((item, i) => !b.items[i] || (item.optional && b.items[i].optional) || intersects(item, b.items[i]));
+    }
+    if (a.kind === 'object' && b.kind === 'object') {
+        for (const name of new Set([...Object.keys(a.fields), ...Object.keys(b.fields)])) {
+            const x = a.fields[name], y = b.fields[name];
+            if (!x || !y) {
+                if (!(x ?? y).optional)
+                    return false;
+            }
+            else if (!(x.optional && y.optional) && !intersects(x, y))
+                return false;
+        }
+    }
+    return true;
+}
+export function validateKeySeparation(queries) {
+    const shapes = queries.map(query => shape(queryTemplate(query), query));
+    for (let i = 0; i < queries.length; i++)
+        for (let j = i + 1; j < queries.length; j++) {
+            if (intersects(shapes[i], shapes[j]))
+                throw new Error('CACHE_KEY_COLLISION:' + queries[i].operationId + ':' + queries[j].operationId);
+        }
+}
+function guarantees(node, filter) {
+    if (node.optional)
+        return false;
+    if (node.kind === 'literal')
+        return canonical(node.value) === canonical(filter);
+    if (node.kind === 'dynamic') {
+        return 'enum' in node.schema && !!node.schema.enum?.length &&
+            node.schema.enum.every(value => canonical(value) === canonical(filter));
+    }
+    if (node.kind === 'array')
+        return Array.isArray(filter) &&
+            filter.every((value, index) => !!node.items[index] && guarantees(node.items[index], value));
+    return !!filter && !Array.isArray(filter) && typeof filter === 'object' &&
+        Object.entries(filter).every(([name, value]) => !!node.fields[name] && guarantees(node.fields[name], value));
+}
+export function validateFallback(query) {
+    if (!Array.isArray(query.fallback) || !query.fallback.length || !isCacheValue(query.fallback) ||
+        !guarantees(shape(queryTemplate(query), query), query.fallback))
+        throw new Error('CACHE_FALLBACK_NOT_PROVEN:' + query.operationId);
+}
+const UNKNOWN = Symbol('unknown');
+function render(node, query, input, partial) {
+    switch (node.kind) {
+        case 'literal': return { value: node.value, complete: true };
+        case 'input': return own(input, node.field)
+            ? { value: input[node.field], complete: true } : { value: partial ? UNKNOWN : OMIT, complete: !partial };
+        case 'inputs': {
+            const names = node.fields ?? Object.keys(query.input);
+            const value = Object.fromEntries(names.filter(name => own(input, name)).map(name => [name, input[name]]));
+            const complete = !partial || names.every(name => own(input, name));
+            return { value: !Object.keys(value).length && node.omitEmpty ? (partial ? UNKNOWN : OMIT) : value, complete };
+        }
+        case 'object': {
+            const result = Object.create(null);
+            let complete = true;
+            for (const [name, child] of Object.entries(node.fields)) {
+                const value = render(child, query, input, partial);
+                complete &&= value.complete;
+                if (value.value !== OMIT && value.value !== UNKNOWN)
+                    result[name] = value.value;
+            }
+            return { value: result, complete };
+        }
+        case 'array': {
+            const result = [];
+            let complete = true;
+            for (const child of node.items) {
+                const value = render(child, query, input, partial);
+                complete &&= value.complete;
+                if (value.value === UNKNOWN)
+                    break; // Partial arrays can express only a prefix.
+                if (value.value !== OMIT)
+                    result.push(value.value);
+            }
+            return { value: result, complete };
+        }
+    }
+}
+export function renderKey(query, input, partial = false) {
+    const result = render(queryTemplate(query), query, input, partial);
+    if (!Array.isArray(result.value) || !result.value.length)
+        return { queryKey: query.fallback, exact: false };
+    return { queryKey: result.value, exact: result.complete };
+}

package/dist/types.d.ts

@@ -0,0 +1,113 @@
+import type { Scalar } from '@server-driven-impact/core';
+export type CacheValue = Scalar | readonly CacheValue[] | {
+    readonly [key: string]: CacheValue;
+};
+export type QueryKey = readonly CacheValue[];
+export type CacheInputType = 'string' | 'number' | 'boolean' | 'date-time' | 'array' | 'object';
+interface FieldOptions {
+    required?: boolean;
+    nullable?: boolean;
+    default?: CacheValue;
+}
+export type CacheInputField = (FieldOptions & {
+    type: 'string' | 'number' | 'boolean' | 'date-time';
+    coerce?: boolean;
+    exclude?: readonly Scalar[];
+    /** Finite normalized domain; also permits exhaustive equality proofs. */
+    enum?: readonly Scalar[];
+    /** UUID input is validated and lowercased on both request and key paths. */
+    format?: 'uuid';
+}) | (FieldOptions & {
+    type: 'array';
+    items: CacheInputField;
+    order?: 'preserve' | 'set';
+}) | (FieldOptions & {
+    type: 'object';
+    properties: Readonly<Record<string, CacheInputField>>;
+});
+/** Tagged nodes avoid confusing literal user objects with template instructions. */
+export type CacheKeyNode = {
+    kind: 'literal';
+    value: CacheValue;
+} | {
+    kind: 'input';
+    field: string;
+} | {
+    kind: 'inputs';
+    fields?: readonly string[];
+    omitEmpty?: boolean;
+} | {
+    kind: 'array';
+    items: readonly CacheKeyNode[];
+} | {
+    kind: 'object';
+    fields: Readonly<Record<string, CacheKeyNode>>;
+};
+export interface FlatCacheKeyTemplate {
+    prefix: QueryKey;
+    path?: readonly string[];
+    params?: readonly string[];
+    /** Required whenever a nonempty params object is present. */
+    paramsAnchor?: readonly string[];
+    omitEmptyParams?: boolean;
+}
+export type CacheKeyTemplate = FlatCacheKeyTemplate | {
+    template: CacheKeyNode;
+};
+export interface CacheQueryContract {
+    operationId: string;
+    endpoint: string;
+    kind: 'query' | 'infinite';
+    input: Readonly<Record<string, CacheInputField>>;
+    /** Execution-only page values, never accepted by buildQueryKey. Infinite only. */
+    pageInput?: Readonly<Record<string, CacheInputField>>;
+    key: CacheKeyTemplate;
+    /** Partial TanStack filter proven to cover all generated operation keys. */
+    fallback: QueryKey;
+    invalidation?: 'preserve' | 'endpoint';
+}
+export interface CacheContract {
+    id: string;
+    version: number;
+    queries: readonly CacheQueryContract[];
+    excludedEndpoints?: readonly {
+        endpoint: string;
+        reason: 'no-store' | 'not-consumed';
+    }[];
+}
+export interface CacheContractReference {
+    id: string;
+    version: number;
+}
+export interface CacheInvalidation {
+    queryKey: QueryKey;
+    exact: boolean;
+}
+export interface CacheInvalidationSet {
+    protocolVersion: 1;
+    contractId: string;
+    contractVersion: number;
+    scope: Scalar;
+    invalidations: readonly CacheInvalidation[];
+}
+export type CacheDiagnosticReason = 'all' | 'endpoint-policy' | 'precise' | 'missing-field' | 'comparison-unproven' | 'input-unrepresentable' | 'page-input' | 'budget' | 'excluded';
+export interface CacheDiagnostic {
+    endpoint: string;
+    operationId?: string;
+    reason: CacheDiagnosticReason;
+    selectorKind?: 'all' | 'inputs';
+    selectorFields?: readonly string[];
+    filterCount: number;
+}
+export interface CacheCompileOptions {
+    /** Metadata only: no selector values or user input are sent to this callback. */
+    explain?: (diagnostic: CacheDiagnostic) => void;
+    maxInvalidations?: number;
+    maxBytes?: number;
+}
+export interface CacheEndpoint {
+    endpoint: string;
+    cache: 'cacheable' | 'no-store';
+}
+export type StringComparisonStatus = 'verified' | 'comparison-unproven';
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+// @ts-self-types="./types.d.ts"
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@server-driven-impact/cache-contract",
+  "version": "0.5.0-cache-contract.2",
+  "description": "Versioned cache-key contracts and invalidation compilation for Server-Driven Impact.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "README.ko.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@server-driven-impact/core": "^0.5.0-cache-contract.2"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woohyun-park/server-driven-impact.git",
+    "directory": "packages/sdi-cache-contract"
+  },
+  "homepage": "https://github.com/woohyun-park/server-driven-impact/tree/main/packages/sdi-cache-contract#readme",
+  "bugs": {
+    "url": "https://github.com/woohyun-park/server-driven-impact/issues"
+  },
+  "keywords": [
+    "cache",
+    "invalidation",
+    "openapi",
+    "query-key"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/backend/clean-sdi-package.mjs && tsc -p tsconfig.json && node ../../scripts/backend/annotate-sdi-package.mjs",
+    "typecheck": "tsc -p tsconfig.check.json"
+  }
+}