@fourier-labs/harbour-contracts 0.3.1 → 0.5.0

package/dist/resolver/index.js

@@ -0,0 +1,679 @@
+/**
+ * Harbour AI policy resolver — the ONE hardened five-layer merge, shipped with
+ * the contracts package so governance and the gateway resolve identically
+ * (completion-spec D-6). Extracted from
+ * `harbour-governance-control-plane/src/ai-governance.ts` (merge machinery)
+ * and `src/ai-platform-controls.ts` (platform baseline + classification
+ * floor) as PURE functions over the contracted snapshot types: no store, no
+ * service, no I/O, no crypto.
+ *
+ * Five-layer resolution per LLD §6.3 (lines 525-542): platform baseline →
+ * data-classification minimum → tenant published defaults → application
+ * published assignment → version runtime contract. Later layers narrow
+ * earlier ones; an application snapshot never replaces the tenant snapshot.
+ *
+ * The merge is TENANT-WINS by default. Three structural defenses carried over
+ * from the governance hardening rounds:
+ *
+ * - `narrowField` — ONE CONTROL, ONE GUARD. The clamp is the single statement
+ *   of each control and the rejection is DERIVED from it (a value the clamp
+ *   had to change is an attempted widening, which §6.3 line 540 requires to be
+ *   rejected rather than silently narrowed), so deleting the clamp always
+ *   changes an observable outcome and every control is mutation-testable.
+ * - `narrowEntry` closes the FIELD-level default: only fields on an explicit
+ *   per-family opt-in list may differ from the tenant entry; every other field
+ *   — including any field a future contract revision adds — is tenant-locked.
+ * - `mergeKeyedFamily` closes the ENTRY-level default: both directions of the
+ *   key set (a tenant key the application omits, and an application key the
+ *   tenant never published) must be stated per family; there is no permissive
+ *   fallthrough for an unenumerated key.
+ *
+ * The `Narrowed` brand is the registry's type-level counterpart: a family
+ * merge must RETURN a `Narrowed` value, and the brand is granted only by the
+ * narrowing combinators, so a passthrough `(tenant, application) =>
+ * application` fails to compile and a deliberate escape requires a visible
+ * cast.
+ */
+/** Version of the resolver ALGORITHM (merge rules + floor artifacts), not of
+ * the package. Consumers record it beside the composite policy digest so a
+ * behavioral divergence between two deployments is attributable to a resolver
+ * revision rather than guessed at. Bump on ANY change to the merge rules, the
+ * platform baseline, or the classification minimums. */
+export const RESOLVER_VERSION = "1.0.0";
+const PII_INPUT_GUARDRAIL = { ruleId: "platform.pii.input", detectorId: "harbour.pii", detectorVersion: "1.0", phase: "input", action: "REDACT" };
+const PII_OUTPUT_GUARDRAIL = { ruleId: "platform.pii.output", detectorId: "harbour.pii", detectorVersion: "1.0", phase: "output", action: "REDACT" };
+const SECRET_OUTPUT_GUARDRAIL = { ruleId: "platform.secret.output", detectorId: "harbour.secret", detectorVersion: "1.0", phase: "output", action: "BLOCK" };
+export const AI_PLATFORM_BASELINE = {
+    schema: "harbour.ai-platform-baseline/1.0",
+    artifactVersion: "1.0.0",
+    controls: {
+        permittedProviderTypes: ["anthropic", "gemini", "openai", "openrouter"],
+        requireApprovedModels: false,
+        maxCaptureMode: "BEST_EFFORT",
+        maxRetentionDays: 90,
+        maxRequestBytes: 1_000_000,
+        maxInputTokens: 200_000,
+        maxOutputTokens: 32_000,
+        maxRequestsPerMinute: 6_000,
+        maxTokensPerMinute: 10_000_000,
+        maxMonthlyBudgetMicroUsd: 1_000_000_000_000,
+        permittedRequestFields: { temperature: true, maxOutputTokens: true, responseFormat: true, tools: true },
+        requiredGuardrails: [],
+    },
+};
+/** LLD §17 item 11 (line 1225) leaves the per-class values to be agreed with
+ * the security-assurance workstream; these are the initial code-owned values
+ * and are versioned by `artifactVersion` plus `RESOLVER_VERSION`. */
+export const AI_CLASSIFICATION_MINIMUMS = {
+    schema: "harbour.ai-classification-minimums/1.0",
+    artifactVersion: "1.0.0",
+    defaultClassification: "Yellow",
+    classes: {
+        Green: {
+            permittedProviderTypes: ["anthropic", "gemini", "openai", "openrouter"],
+            requireApprovedModels: false,
+            maxCaptureMode: "BEST_EFFORT",
+            maxRetentionDays: 90,
+            maxRequestBytes: 1_000_000,
+            maxInputTokens: 200_000,
+            maxOutputTokens: 32_000,
+            maxRequestsPerMinute: 6_000,
+            maxTokensPerMinute: 10_000_000,
+            maxMonthlyBudgetMicroUsd: 1_000_000_000_000,
+            permittedRequestFields: { temperature: true, maxOutputTokens: true, responseFormat: true, tools: true },
+            requiredGuardrails: [],
+        },
+        Yellow: {
+            permittedProviderTypes: ["anthropic", "gemini", "openai", "openrouter"],
+            requireApprovedModels: true,
+            maxCaptureMode: "BEST_EFFORT",
+            maxRetentionDays: 60,
+            maxRequestBytes: 1_000_000,
+            maxInputTokens: 200_000,
+            maxOutputTokens: 32_000,
+            maxRequestsPerMinute: 6_000,
+            maxTokensPerMinute: 10_000_000,
+            maxMonthlyBudgetMicroUsd: 1_000_000_000_000,
+            permittedRequestFields: { temperature: true, maxOutputTokens: true, responseFormat: true, tools: true },
+            requiredGuardrails: [],
+        },
+        Orange: {
+            permittedProviderTypes: ["anthropic", "gemini", "openai"],
+            requireApprovedModels: true,
+            maxCaptureMode: "BEST_EFFORT",
+            maxRetentionDays: 30,
+            maxRequestBytes: 500_000,
+            maxInputTokens: 100_000,
+            maxOutputTokens: 16_000,
+            maxRequestsPerMinute: 1_200,
+            maxTokensPerMinute: 2_000_000,
+            maxMonthlyBudgetMicroUsd: 100_000_000_000,
+            permittedRequestFields: { temperature: true, maxOutputTokens: true, responseFormat: true, tools: false },
+            requiredGuardrails: [PII_OUTPUT_GUARDRAIL],
+        },
+        Red: {
+            permittedProviderTypes: ["anthropic", "openai"],
+            requireApprovedModels: true,
+            maxCaptureMode: "OFF",
+            maxRetentionDays: 7,
+            maxRequestBytes: 200_000,
+            maxInputTokens: 50_000,
+            maxOutputTokens: 8_000,
+            maxRequestsPerMinute: 300,
+            maxTokensPerMinute: 500_000,
+            maxMonthlyBudgetMicroUsd: 10_000_000_000,
+            permittedRequestFields: { temperature: false, maxOutputTokens: true, responseFormat: false, tools: false },
+            requiredGuardrails: [PII_INPUT_GUARDRAIL, PII_OUTPUT_GUARDRAIL, SECRET_OUTPUT_GUARDRAIL],
+        },
+    },
+};
+export const CAPTURE_MODE_RANK = { OFF: 0, BEST_EFFORT: 1, REQUIRED: 2 };
+/** Ascending strictness. Used to fail closed on the classification layer: an
+ * application-published snapshot may raise the class but never lower it. */
+export const CLASSIFICATION_RANK = { Green: 0, Yellow: 1, Orange: 2, Red: 3 };
+export function strictestClassification(left, right) {
+    return CLASSIFICATION_RANK[left] >= CLASSIFICATION_RANK[right] ? left : right;
+}
+export const GUARDRAIL_ACTION_RANK = { ALLOW: 0, OBSERVE: 1, REDACT: 2, BLOCK: 3 };
+/** Element-wise most restrictive of two control sets. Used to fold the
+ * classification minimum into the platform baseline before any tenant or
+ * application layer is applied. */
+export function narrowControls(left, right) {
+    const guardrails = new Map();
+    for (const guardrail of [...left.requiredGuardrails, ...right.requiredGuardrails]) {
+        const existing = guardrails.get(guardrail.ruleId);
+        if (!existing || GUARDRAIL_ACTION_RANK[guardrail.action] > GUARDRAIL_ACTION_RANK[existing.action])
+            guardrails.set(guardrail.ruleId, guardrail);
+    }
+    return {
+        permittedProviderTypes: left.permittedProviderTypes.filter(type => right.permittedProviderTypes.includes(type)).sort(),
+        requireApprovedModels: left.requireApprovedModels || right.requireApprovedModels,
+        maxCaptureMode: CAPTURE_MODE_RANK[left.maxCaptureMode] <= CAPTURE_MODE_RANK[right.maxCaptureMode] ? left.maxCaptureMode : right.maxCaptureMode,
+        maxRetentionDays: Math.min(left.maxRetentionDays, right.maxRetentionDays),
+        maxRequestBytes: Math.min(left.maxRequestBytes, right.maxRequestBytes),
+        maxInputTokens: Math.min(left.maxInputTokens, right.maxInputTokens),
+        maxOutputTokens: Math.min(left.maxOutputTokens, right.maxOutputTokens),
+        maxRequestsPerMinute: Math.min(left.maxRequestsPerMinute, right.maxRequestsPerMinute),
+        maxTokensPerMinute: Math.min(left.maxTokensPerMinute, right.maxTokensPerMinute),
+        maxMonthlyBudgetMicroUsd: Math.min(left.maxMonthlyBudgetMicroUsd, right.maxMonthlyBudgetMicroUsd),
+        permittedRequestFields: {
+            temperature: left.permittedRequestFields.temperature && right.permittedRequestFields.temperature,
+            maxOutputTokens: left.permittedRequestFields.maxOutputTokens && right.permittedRequestFields.maxOutputTokens,
+            responseFormat: left.permittedRequestFields.responseFormat && right.permittedRequestFields.responseFormat,
+            tools: left.permittedRequestFields.tools && right.permittedRequestFields.tools,
+        },
+        requiredGuardrails: [...guardrails.values()].sort((first, second) => first.ruleId.localeCompare(second.ruleId)),
+    };
+}
+/** Platform baseline folded with one classification's minimum control set:
+ * layers 1 and 2 of §6.3 as a single floor that later layers may only narrow. */
+export function classificationFloor(classification) {
+    return narrowControls(AI_PLATFORM_BASELINE.controls, AI_CLASSIFICATION_MINIMUMS.classes[classification]);
+}
+// ---------------------------------------------------------------------------
+// Errors and stable codes.
+// ---------------------------------------------------------------------------
+/** Every rejection carries a stable code and HTTP-shaped status so both
+ * resolver consumers surface identical errors for identical escapes. */
+export class AiPolicyResolutionError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "AiPolicyResolutionError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Stable codes for a later layer that tried to widen, not narrow, an earlier
+ * one (LLD §6.3 line 540). The audit acceptance criterion is rejection, never
+ * silent narrowing. */
+export const WIDENS_TENANT_ALLOWLIST = "configuration_widens_tenant_allowlist";
+export const RAISES_TENANT_CEILING = "configuration_raises_tenant_ceiling";
+export const WEAKENS_TENANT_GUARDRAIL = "configuration_weakens_tenant_guardrail";
+/** An application entry tried to change a field only the tenant may set. */
+export const OVERRIDES_TENANT_LOCKED = "configuration_overrides_tenant_locked_field";
+/** The merge output outgrew a `maxItems` bound of the snapshot contract. */
+export const EXCEEDS_CONTRACT_BOUNDS = "configuration_exceeds_contract_bounds";
+function narrowingConflict(code, message) {
+    return new AiPolicyResolutionError(409, code, message);
+}
+/** Canonical JSON with sorted object keys — the equality the tenant-locked
+ * comparisons are stated in, so key order can never disguise a difference. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const key of Object.keys(value).sort()) {
+            output[key] = sortValue(value[key]);
+        }
+        return output;
+    }
+    return value;
+}
+function asNarrowed(value) {
+    return value;
+}
+/** ONE CONTROL, ONE GUARD: the clamp is the single statement of the control
+ * and the rejection is derived from it, so deleting the clamp always changes
+ * an observable outcome and the control is mutation-testable. */
+export function narrowField(tenant, application, clamp, code, describe) {
+    const narrowed = clamp(tenant, application);
+    if (canonicalJson(narrowed) !== canonicalJson(application))
+        throw narrowingConflict(code, describe());
+    return narrowed;
+}
+/** Merges one application entry over its tenant counterpart so that
+ * TENANT-WINS is the DEFAULT: only fields named in `narrowable` are replaced
+ * by the caller-computed `narrowed` values; every other field — including any
+ * field a future contract revision adds — must equal the tenant value or the
+ * entry is rejected. Spreading the application entry is never correct here. */
+export function narrowEntry(tenant, application, narrowable, narrowed, describe) {
+    const tenantRecord = tenant;
+    const applicationRecord = application;
+    for (const field of new Set([...Object.keys(tenantRecord), ...Object.keys(applicationRecord)])) {
+        if (narrowable.includes(field))
+            continue;
+        if (canonicalJson(tenantRecord[field]) !== canonicalJson(applicationRecord[field]))
+            throw narrowingConflict(OVERRIDES_TENANT_LOCKED, describe(field));
+    }
+    return asNarrowed({ ...tenant, ...narrowed });
+}
+/** The single path by which any key-addressed family merges: no per-family
+ * loop can quietly grow its own `if (!base)` branch. */
+export function mergeKeyedFamily(tenant, application, rules) {
+    const permitted = new Map(tenant.map(entry => [rules.key(entry), entry]));
+    const merged = rules.omittedByApplication === "keep" ? new Map(permitted) : new Map();
+    for (const entry of application) {
+        const key = rules.key(entry);
+        const base = permitted.get(key);
+        if (base) {
+            merged.set(key, rules.narrow(base, entry));
+            continue;
+        }
+        if (rules.added.decision === "reject")
+            throw narrowingConflict(rules.added.code, rules.added.describe(entry));
+        merged.set(key, rules.added.admit(entry));
+    }
+    // Sorted, not insertion-ordered: the merged set feeds the composite
+    // policyDigest, so two runs that differ only in the order the application
+    // listed its entries must produce the same digest.
+    return asNarrowed([...merged.values()].sort((first, second) => rules.key(first).localeCompare(rules.key(second))));
+}
+// ---------------------------------------------------------------------------
+// The assigned capability set (a GRANT, not a control value).
+// ---------------------------------------------------------------------------
+/** A grant can only flow down: an application may drop a capability, but may
+ * neither assign one the tenant did not assign nor repoint an assignment at
+ * another route. `{ ...tenant, ...application }` made the application the
+ * authority for both. */
+export function mergeModelAliases(tenant, application) {
+    const merged = ["generation", "embeddings"].map(capability => {
+        const assigned = application[capability];
+        if (assigned === undefined)
+            return {};
+        const granted = tenant[capability];
+        if (granted === undefined) {
+            throw narrowingConflict(WIDENS_TENANT_ALLOWLIST, `The application configuration assigns the "${capability}" capability, which the tenant configuration does not assign.`);
+        }
+        if (assigned !== granted) {
+            throw narrowingConflict(OVERRIDES_TENANT_LOCKED, `The application configuration points the "${capability}" model alias at route "${assigned}" rather than the tenant route "${granted}".`);
+        }
+        return { [capability]: granted };
+    });
+    // The "no capability is assigned at all" case is deliberately not thrown
+    // here: the caller states it once on the returned value, so the guard stays
+    // reachable and testable in exactly one place.
+    const aliases = Object.assign({}, ...merged);
+    return aliases;
+}
+// ---------------------------------------------------------------------------
+// Per-family merges (layers 3 and 4).
+// ---------------------------------------------------------------------------
+const minimum = (tenantValue, applicationValue) => Math.min(tenantValue, applicationValue);
+const both = (tenantValue, applicationValue) => tenantValue && applicationValue;
+const either = (tenantValue, applicationValue) => tenantValue || applicationValue;
+const intersect = (tenantValue, applicationValue) => applicationValue.filter(item => tenantValue.includes(item));
+/** Only `enabled` may be narrowed. `baseUrl` and `credentialSecretRef` in
+ * particular are tenant-locked: an application that could set them would
+ * repoint a tenant-approved provider id at its own endpoint or credential. */
+const PROVIDER_NARROWABLE = ["enabled"];
+function mergeProviders(tenant, application) {
+    return mergeKeyedFamily(tenant, application, {
+        key: entry => entry.id,
+        omittedByApplication: "drop",
+        added: { decision: "reject", code: WIDENS_TENANT_ALLOWLIST, describe: entry => `The application configuration permits provider "${entry.id}", which the tenant configuration does not permit.` },
+        narrow: (base, entry) => narrowEntry(base, entry, PROVIDER_NARROWABLE, {
+            enabled: narrowField(base.enabled, entry.enabled, both, WIDENS_TENANT_ALLOWLIST, () => `The application configuration enables provider "${entry.id}", which the tenant configuration disables.`),
+        }, field => `The application configuration changes the tenant-locked field "${field}" of provider "${entry.id}".`),
+    });
+}
+/** `providerModel` is tenant-locked: the allowlist keys on `id`, so a swappable
+ * `providerModel` would let an application send a different wire model behind
+ * an approved identifier. `pricing` is tenant-locked too, because every cost
+ * and budget ceiling is computed from it. */
+const MODEL_NARROWABLE = ["approved", "capabilities"];
+function mergeModels(tenant, application) {
+    return mergeKeyedFamily(tenant, application, {
+        key: entry => entry.id,
+        omittedByApplication: "drop",
+        added: { decision: "reject", code: WIDENS_TENANT_ALLOWLIST, describe: entry => `The application configuration permits model "${entry.id}", which the tenant configuration does not permit.` },
+        narrow: (base, entry) => narrowEntry(base, entry, MODEL_NARROWABLE, {
+            approved: narrowField(base.approved, entry.approved, both, WIDENS_TENANT_ALLOWLIST, () => `The application configuration approves model "${entry.id}", which the tenant configuration does not approve.`),
+            // The contracted capabilities type is a bounded tuple; the intersection
+            // preserves the application's order and can only shrink, so the cast
+            // back to the tuple union is sound.
+            capabilities: narrowField(base.capabilities, entry.capabilities, (tenantValue, applicationValue) => intersect(tenantValue, applicationValue), WIDENS_TENANT_ALLOWLIST, () => `The application configuration adds a capability to model "${entry.id}" that the tenant configuration does not permit.`),
+        }, field => `The application configuration changes the tenant-locked field "${field}" of model "${entry.id}".`),
+    });
+}
+/** An application may re-target a shared alias only within the tenant route's
+ * own target set, and `retryCount`/`timeoutMs` are ceilings it may only lower.
+ * `capability` is tenant-locked. */
+const ROUTE_NARROWABLE = ["version", "targets", "retryCount", "timeoutMs"];
+/** A route alias is a named path with its own retry, timeout and target
+ * ceilings. An alias the tenant never published is a path the tenant never
+ * bounded, so publishing one is a widening even when every model it reaches is
+ * on the intersected allowlist. */
+function mergeRoutes(tenant, application) {
+    return mergeKeyedFamily(tenant, application, {
+        key: route => route.alias,
+        omittedByApplication: "keep",
+        added: { decision: "reject", code: WIDENS_TENANT_ALLOWLIST, describe: route => `The application configuration publishes route "${route.alias}", which the tenant configuration does not publish.` },
+        narrow: (base, route) => narrowEntry(base, route, ROUTE_NARROWABLE, {
+            // `version` is snapshot metadata rather than a control, so it is the
+            // later of the two rather than a ceiling the application may not raise.
+            version: Math.max(base.version, route.version),
+            targets: mergeRouteTargets(base, route),
+            retryCount: narrowField(base.retryCount, route.retryCount, minimum, RAISES_TENANT_CEILING, () => `The application route "${route.alias}" raises retryCount above the tenant ceiling.`),
+            timeoutMs: narrowField(base.timeoutMs, route.timeoutMs, minimum, RAISES_TENANT_CEILING, () => `The application route "${route.alias}" raises timeoutMs above the tenant ceiling.`),
+        }, field => `The application configuration changes the tenant-locked field "${field}" of route "${route.alias}".`),
+    });
+}
+/** Per §7.4 the ORDER of a target list is the control: lower `priority` is
+ * attempted first and `weight` shares traffic inside a priority group, so an
+ * application keeping exactly the tenant's target set can still redirect every
+ * request by renumbering. The only narrowing a target list admits is DROPPING
+ * targets: survivors keep the tenant's weight and the tenant's relative order
+ * (priorities compared as dense ranks), and any reordering, regrouping,
+ * repetition or re-weighting is rejected. */
+function mergeRouteTargets(tenant, application) {
+    const permitted = new Map(tenant.targets.map(target => [target.modelId, target]));
+    const kept = new Set();
+    for (const target of application.targets) {
+        const base = permitted.get(target.modelId);
+        if (!base)
+            throw narrowingConflict(WIDENS_TENANT_ALLOWLIST, `The application route "${application.alias}" targets model "${target.modelId}", which the tenant route does not target.`);
+        if (kept.has(target.modelId))
+            throw narrowingConflict(OVERRIDES_TENANT_LOCKED, `The application route "${application.alias}" repeats target model "${target.modelId}", which shifts traffic the tenant route did not.`);
+        kept.add(target.modelId);
+        if (target.weight !== base.weight)
+            throw narrowingConflict(OVERRIDES_TENANT_LOCKED, `The application route "${application.alias}" changes the tenant traffic weight of target model "${target.modelId}".`);
+    }
+    const tenantOrder = new Map(priorityRanks(tenant.targets.filter(target => kept.has(target.modelId))));
+    for (const [modelId, rank] of priorityRanks(application.targets)) {
+        if (tenantOrder.get(modelId) !== rank) {
+            throw narrowingConflict(OVERRIDES_TENANT_LOCKED, `The application route "${application.alias}" reorders target model "${modelId}" against the tenant route's attempt order.`);
+        }
+    }
+    return application.targets;
+}
+/** Each target's priority as a dense rank over the distinct priorities present,
+ * so `0,1` and `0,9` describe the same attempt order and `0,0` does not. */
+function priorityRanks(targets) {
+    const distinct = [...new Set(targets.map(target => target.priority))].sort((first, second) => first - second);
+    return targets.map(target => [target.modelId, distinct.indexOf(target.priority)]);
+}
+/** A rule set is a named ceiling and permitted-field set that a request
+ * selects by name; a name the tenant never published is a selectable ceiling
+ * set the tenant never bounded. */
+function mergePolicies(tenant, application) {
+    return mergeKeyedFamily(tenant, application, {
+        key: entry => entry.name,
+        omittedByApplication: "keep",
+        added: { decision: "reject", code: WIDENS_TENANT_ALLOWLIST, describe: entry => `The application configuration publishes policy "${entry.name}", which the tenant configuration does not publish.` },
+        narrow: mergePolicyEntry,
+    });
+}
+const PERMITTED_REQUEST_FIELDS = ["temperature", "maxOutputTokens", "responseFormat", "tools"];
+function mergePolicyEntry(tenant, application) {
+    const ceiling = (field) => narrowField(tenant[field], application[field], minimum, RAISES_TENANT_CEILING, () => `The application policy "${application.name}" raises ${field} above the tenant ceiling.`);
+    const permittedRequestFields = {};
+    for (const field of PERMITTED_REQUEST_FIELDS) {
+        permittedRequestFields[field] = narrowField(tenant.permittedRequestFields[field], application.permittedRequestFields[field], both, WIDENS_TENANT_ALLOWLIST, () => `The application policy "${application.name}" permits the request field "${field}", which the tenant policy forbids.`);
+    }
+    return narrowEntry(tenant, application, POLICY_NARROWABLE, {
+        // Snapshot metadata rather than a control, so the later revision wins.
+        version: Math.max(tenant.version, application.version),
+        maxRequestBytes: ceiling("maxRequestBytes"),
+        maxInputTokens: ceiling("maxInputTokens"),
+        maxOutputTokens: ceiling("maxOutputTokens"),
+        // Buffering the response is a restriction (nothing reaches the caller
+        // before the output guardrails have run), so it unions like the enabled
+        // state of a limit; turning the tenant's buffering off is a weakening.
+        bufferedDelivery: narrowField(tenant.bufferedDelivery, application.bufferedDelivery, either, RAISES_TENANT_CEILING, () => `The application policy "${application.name}" disables the buffered delivery the tenant policy requires.`),
+        permittedRequestFields,
+        guardrails: mergeGuardrails(tenant.guardrails, application.guardrails, application.name),
+    }, field => `The application policy "${application.name}" changes the tenant-locked field "${field}".`);
+}
+/** Every rule-set field except the `name` key is explicitly merged above; a
+ * field a later contract revision adds is tenant-locked until it is listed. */
+const POLICY_NARROWABLE = ["version", "maxRequestBytes", "maxInputTokens", "maxOutputTokens", "bufferedDelivery", "permittedRequestFields", "guardrails"];
+const GUARDRAIL_NARROWABLE = ["action", "parameters"];
+/** Guardrails are the one family whose merge semantics is union-of-
+ * restrictions, so an application rule the tenant never published is genuinely
+ * narrowing — but only if the rule is itself a restriction:
+ *
+ * - Only `REDACT` and `BLOCK` restrict. `ALLOW` is the identity action and
+ *   `OBSERVE` records-and-permits (the trace contract maps it to `matched`,
+ *   never `blocked`/`redacted`), so a new ruleId carrying either exists only
+ *   to occupy that id.
+ * - An added rule may carry no `parameters`: on a rule the tenant never
+ *   published there is no tenant bound to merge them against, and both
+ *   `allowedTools` (an allowlist) and `jsonSchema`/`jsonSchemaRef` (detector
+ *   configuration) would be application authority over an unbounded surface.
+ *
+ * A shared rule keeps the stronger action; `detectorId`, `detectorVersion`
+ * and `phase` are tenant-locked. */
+function mergeGuardrails(tenant, application, policyName) {
+    return mergeKeyedFamily(tenant, application, {
+        key: rule => rule.ruleId,
+        omittedByApplication: "keep",
+        added: {
+            decision: "permit_when_restrictive",
+            admit: rule => {
+                if (GUARDRAIL_ACTION_RANK[rule.action] < GUARDRAIL_ACTION_RANK.REDACT) {
+                    throw narrowingConflict(WEAKENS_TENANT_GUARDRAIL, `The application policy "${policyName}" publishes guardrail "${rule.ruleId}" with the non-restricting action "${rule.action}", which the tenant configuration does not publish.`);
+                }
+                if (rule.parameters !== undefined) {
+                    throw narrowingConflict(WIDENS_TENANT_ALLOWLIST, `The application policy "${policyName}" publishes guardrail "${rule.ruleId}" with parameters the tenant configuration never bounded.`);
+                }
+                return rule;
+            },
+        },
+        narrow: (base, rule) => {
+            const action = narrowField(base.action, rule.action, (tenantAction, applicationAction) => GUARDRAIL_ACTION_RANK[applicationAction] >= GUARDRAIL_ACTION_RANK[tenantAction] ? applicationAction : tenantAction, WEAKENS_TENANT_GUARDRAIL, () => `The application policy "${policyName}" weakens guardrail "${rule.ruleId}" below the tenant action.`);
+            const parameters = mergeGuardrailParameters(base, rule, policyName);
+            return narrowEntry(base, rule, GUARDRAIL_NARROWABLE, {
+                action,
+                ...(parameters === undefined ? {} : { parameters }),
+            }, field => `The application policy "${policyName}" changes the tenant-locked field "${field}" of guardrail "${rule.ruleId}".`);
+        },
+    });
+}
+/** The merged `parameters` of a shared guardrail. `allowedTools` is an
+ * allowlist and intersects; `jsonSchema`/`jsonSchemaRef` are detector
+ * configuration (the exact output shape an `output.json_schema` rule
+ * enforces) and are tenant-locked — an application that could swap the schema
+ * would replace what the tenant's blocking detector enforces while keeping
+ * its action rank. The tenant value always survives; an application may only
+ * repeat it verbatim or stay silent. */
+function mergeGuardrailParameters(tenant, application, policyName) {
+    const allowedTools = mergeAllowedTools(tenant, application, policyName);
+    const jsonSchema = tenantLockedParameter(tenant, application, "jsonSchema", policyName);
+    const jsonSchemaRef = tenantLockedParameter(tenant, application, "jsonSchemaRef", policyName);
+    const merged = {
+        ...(allowedTools === undefined ? {} : { allowedTools }),
+        ...(jsonSchema === undefined ? {} : { jsonSchema }),
+        ...(jsonSchemaRef === undefined ? {} : { jsonSchemaRef }),
+    };
+    return Object.keys(merged).length === 0 ? undefined : merged;
+}
+function tenantLockedParameter(tenant, application, field, policyName) {
+    const granted = tenant.parameters?.[field];
+    const requested = application.parameters?.[field];
+    if (requested !== undefined && canonicalJson(requested) !== canonicalJson(granted)) {
+        throw narrowingConflict(OVERRIDES_TENANT_LOCKED, `The application policy "${policyName}" changes the tenant-locked parameter "${field}" of guardrail "${application.ruleId}".`);
+    }
+    return granted;
+}
+function mergeAllowedTools(tenant, application, policyName) {
+    const permitted = tenant.parameters?.allowedTools;
+    const requested = application.parameters?.allowedTools;
+    if (requested === undefined)
+        return permitted;
+    if (permitted === undefined) {
+        // FAIL CLOSED. `allowedTools` is an allowlist, so tenant SILENCE is not
+        // tenant CONSENT: a tenant guardrail that names no tool has permitted no
+        // tool by name, and an application list is a widening of nothing.
+        throw narrowingConflict(WIDENS_TENANT_ALLOWLIST, `The application policy "${policyName}" permits tool "${requested[0]}" for guardrail "${application.ruleId}", which the tenant policy does not permit.`);
+    }
+    return narrowField(permitted, requested, (tenantValue, applicationValue) => intersect(tenantValue, applicationValue), WIDENS_TENANT_ALLOWLIST, () => `The application policy "${policyName}" permits tool "${requested.find(tool => !permitted.includes(tool))}" for guardrail "${application.ruleId}", which the tenant policy does not permit.`);
+}
+const LIMIT_NARROWABLE = ["enabled", "requestsPerMinute", "tokensPerMinute", "monthlyBudgetMicroUsd"];
+/** A limit is a named budget bucket that the runtime selects by `scope`, so a
+ * name the tenant never published is not an extra restriction: it is a second
+ * bucket at the same scope whose ceiling no tenant entry bounds. */
+function mergeLimits(tenant, application) {
+    return mergeKeyedFamily(tenant, application, {
+        key: entry => entry.name,
+        omittedByApplication: "keep",
+        added: { decision: "reject", code: WIDENS_TENANT_ALLOWLIST, describe: entry => `The application configuration publishes limit "${entry.name}", which the tenant configuration does not publish.` },
+        // `scope` is tenant-locked: re-scoping a tenant-wide budget to the
+        // application would give every application its own copy of the ceiling.
+        narrow: (base, entry) => {
+            const ceiling = (field) => narrowField(base[field], entry[field], minimum, RAISES_TENANT_CEILING, () => `The application limit "${entry.name}" raises ${field} above the tenant ceiling.`);
+            return narrowEntry(base, entry, LIMIT_NARROWABLE, {
+                enabled: narrowField(base.enabled, entry.enabled, either, RAISES_TENANT_CEILING, () => `The application configuration disables the enabled tenant limit "${entry.name}".`),
+                requestsPerMinute: ceiling("requestsPerMinute"),
+                tokensPerMinute: ceiling("tokensPerMinute"),
+                monthlyBudgetMicroUsd: ceiling("monthlyBudgetMicroUsd"),
+            }, field => `The application configuration changes the tenant-locked field "${field}" of limit "${entry.name}".`);
+        },
+    });
+}
+const RETENTION_NARROWABLE = ["captureMode", "retentionDays", "revealRoles"];
+function mergeRetention(tenant, application) {
+    return narrowEntry(tenant, application, RETENTION_NARROWABLE, {
+        captureMode: narrowField(tenant.captureMode, application.captureMode, (tenantMode, applicationMode) => CAPTURE_MODE_RANK[applicationMode] <= CAPTURE_MODE_RANK[tenantMode] ? applicationMode : tenantMode, RAISES_TENANT_CEILING, () => "The application configuration raises the capture mode above the tenant ceiling."),
+        retentionDays: narrowField(tenant.retentionDays, application.retentionDays, minimum, RAISES_TENANT_CEILING, () => "The application configuration raises retentionDays above the tenant ceiling."),
+        // The contracted reveal-role list is a bounded tuple; an intersection can
+        // only shrink it, so the cast back to the tuple union is sound.
+        revealRoles: narrowField(tenant.revealRoles, application.revealRoles, (tenantRoles, applicationRoles) => intersect(tenantRoles, applicationRoles), WIDENS_TENANT_ALLOWLIST, () => `The application configuration permits reveal role "${application.revealRoles.find(role => !tenant.revealRoles.includes(role))}", which the tenant configuration does not permit.`),
+    }, field => `The application configuration changes the tenant-locked retention field "${field}".`);
+}
+const SCOPE_FAMILY_MERGES = {
+    providers: mergeProviders,
+    models: mergeModels,
+    routes: mergeRoutes,
+    policies: mergePolicies,
+    limits: mergeLimits,
+    retention: mergeRetention,
+};
+export function scopeFamilies() {
+    return Object.keys(SCOPE_FAMILY_MERGES);
+}
+/** The single-scope projection: the snapshot's policy families with the
+ * identity fields subtracted, re-checked against the contract bounds. */
+export function scopePolicySet(snapshot) {
+    const set = {};
+    for (const family of scopeFamilies())
+        set[family] = snapshot[family];
+    return assertContractBounds(set);
+}
+/** Layers 3 and 4 of §6.3: the application/environment snapshot narrows the
+ * tenant snapshot per family — intersection for allowlists, minimum for
+ * numeric ceilings, union for guardrail restrictions — and any attempt to
+ * widen is rejected. Driven off `SCOPE_FAMILY_MERGES` rather than written out,
+ * so there is no place left for a family to be answered by omission. */
+export function mergeScopeSnapshots(tenant, application) {
+    const merged = {};
+    for (const family of scopeFamilies()) {
+        const merge = SCOPE_FAMILY_MERGES[family];
+        merged[family] = merge(tenant[family], application[family]);
+    }
+    return assertContractBounds(merged);
+}
+/** An application entry the merge admits — today only a restricting guardrail
+ * the tenant never published — is the one way the merge OUTPUT can be larger
+ * than either input, so the merged set and the effective set are both
+ * re-validated against every `maxItems` in
+ * `schema/ai-policy-snapshot.schema.json`. */
+export function assertContractBounds(set) {
+    const counted = [
+        ["providers", set.providers.length, 64],
+        ["models", set.models.length, 512],
+        ["routes", set.routes.length, 256],
+        ["policies", set.policies.length, 256],
+        ["limits", set.limits.length, 128],
+        ["retention reveal roles", set.retention.revealRoles.length, 16],
+        ...set.routes.map(route => [`targets of route "${route.alias}"`, route.targets.length, 16]),
+        ...set.policies.map(policy => [`guardrails of policy "${policy.name}"`, policy.guardrails.length, 128]),
+    ];
+    for (const [what, size, maximum] of counted) {
+        if (size > maximum) {
+            throw new AiPolicyResolutionError(409, EXCEEDS_CONTRACT_BOUNDS, `The resolved configuration carries ${size} ${what}, above the contract maximum of ${maximum}.`);
+        }
+    }
+    return set;
+}
+// ---------------------------------------------------------------------------
+// The classification floor (layers 1 and 2).
+// ---------------------------------------------------------------------------
+/** The floor is not negotiable, so it clamps the merged tenant/application
+ * set instead of rejecting it: a stamped classification arrives after
+ * publication and must still bind. */
+export function applyControlFloor(merged, floor, classification) {
+    const providers = merged.providers.filter(entry => floor.permittedProviderTypes.includes(entry.provider));
+    const usableProviders = new Set(providers.filter(entry => entry.enabled).map(entry => entry.id));
+    const models = merged.models.filter(entry => usableProviders.has(entry.providerId) && (!floor.requireApprovedModels || entry.approved));
+    const modelsById = new Map(models.map(entry => [entry.id, entry]));
+    const routes = merged.routes
+        // Filtering a bounded tuple can only shrink it; the cast back is sound.
+        .map(route => ({ ...route, targets: route.targets.filter(target => modelsById.get(target.modelId)?.capabilities.includes(route.capability)) }))
+        .filter(route => route.targets.length > 0);
+    const policies = merged.policies.map(policy => {
+        const permittedRequestFields = {};
+        for (const field of PERMITTED_REQUEST_FIELDS) {
+            permittedRequestFields[field] = policy.permittedRequestFields[field] && floor.permittedRequestFields[field];
+        }
+        return {
+            ...policy,
+            maxRequestBytes: Math.min(policy.maxRequestBytes, floor.maxRequestBytes),
+            maxInputTokens: Math.min(policy.maxInputTokens, floor.maxInputTokens),
+            maxOutputTokens: Math.min(policy.maxOutputTokens, floor.maxOutputTokens),
+            permittedRequestFields,
+            guardrails: applyRequiredGuardrails(policy.guardrails, floor.requiredGuardrails),
+        };
+    });
+    const limits = merged.limits.map(limit => ({
+        ...limit,
+        requestsPerMinute: Math.min(limit.requestsPerMinute, floor.maxRequestsPerMinute),
+        tokensPerMinute: Math.min(limit.tokensPerMinute, floor.maxTokensPerMinute),
+        monthlyBudgetMicroUsd: Math.min(limit.monthlyBudgetMicroUsd, floor.maxMonthlyBudgetMicroUsd),
+    }));
+    return assertContractBounds({
+        classification,
+        providers,
+        models,
+        routes,
+        policies,
+        limits,
+        retention: {
+            captureMode: CAPTURE_MODE_RANK[merged.retention.captureMode] <= CAPTURE_MODE_RANK[floor.maxCaptureMode] ? merged.retention.captureMode : floor.maxCaptureMode,
+            retentionDays: Math.min(merged.retention.retentionDays, floor.maxRetentionDays),
+            revealRoles: merged.retention.revealRoles,
+        },
+    });
+}
+/** A platform-required rule's IDENTITY is non-negotiable and replaces whatever
+ * held the id (a snapshot could otherwise pre-occupy a required rule id with a
+ * NOOP detector of its own choosing); only `action` is negotiable, and only
+ * upward. `parameters` go with the displaced entry, because they tune that
+ * entry's detector rather than the platform's. */
+export function applyRequiredGuardrails(guardrails, required) {
+    const byRule = new Map(guardrails.map(rule => [rule.ruleId, rule]));
+    for (const minimumRule of required) {
+        const existing = byRule.get(minimumRule.ruleId);
+        const action = existing && GUARDRAIL_ACTION_RANK[existing.action] > GUARDRAIL_ACTION_RANK[minimumRule.action] ? existing.action : minimumRule.action;
+        byRule.set(minimumRule.ruleId, { ...minimumRule, action });
+    }
+    return [...byRule.values()].sort((first, second) => first.ruleId.localeCompare(second.ruleId));
+}
+// ---------------------------------------------------------------------------
+// Composed resolution over a published scope pair.
+// ---------------------------------------------------------------------------
+/** The snapshot half of five-layer resolution, composed: classification from
+ * the published minimums (strictest wins; the platform default applies when no
+ * layer states one) optionally raised by a stamped classification, the
+ * tenant/application merge (a single present scope resolves alone), then the
+ * classification floor. Version controls (mode, gateway endpoint, alias
+ * grant) live on the published-configuration wrapper, which is not part of
+ * the snapshot contract — both consumers resolve them beside this call, using
+ * `mergeModelAliases` for the grant. */
+export function resolveEffectiveScopePolicy(input) {
+    const { tenant, application, stampedClassification } = input;
+    if (!tenant && !application) {
+        throw new AiPolicyResolutionError(404, "configuration_not_published", "No published configuration exists for this scope.");
+    }
+    const tenantClassification = tenant?.classificationMinimum?.classification ?? AI_CLASSIFICATION_MINIMUMS.defaultClassification;
+    let classification = strictestClassification(tenantClassification, application?.classificationMinimum?.classification ?? tenantClassification);
+    if (stampedClassification)
+        classification = strictestClassification(classification, stampedClassification);
+    const merged = tenant && application ? mergeScopeSnapshots(tenant, application) : scopePolicySet((tenant ?? application));
+    return { classification, effective: applyControlFloor(merged, classificationFloor(classification), classification) };
+}