《互联网产品的 AI 架构·平台化与治理》2.2 提供方与调用方的契约

// file: src/gov/catalog-contract.ts
// tier: L2
// verify: node --test test/gov/catalog.test.ts

import { isValidRange, satisfiesRange } from "../orch/platform.ts";
import type {
  BillingUnit,
  CapabilityEntry,
  FailureMode,
  Responsibility,
} from "./catalog.ts";

export interface Quota {
  monthlyMicros: number;
  perRequestMicros: number;
}

export interface RetryPolicy {
  attempts: number;
  idempotencyKey: boolean;
  backoffMs: number;
}

export interface CachePolicy {
  key: readonly string[];
  ttlSeconds: number;
}

export interface InputGuard {
  field: string;
  maxBytes: number;
}

/** The consumer half of a capability contract. The entry is the provider half. */
export interface ConsumerContract {
  consumer: string;
  capability: string;
  versionRange: string;
  inputGuards: readonly InputGuard[];
  quota: Quota;
  retry: RetryPolicy;
  cache: CachePolicy;
  feedbackChannel: string;
}

export type ContractIssueCode =
  | "missing-consumer"
  | "unknown-capability"
  | "invalid-range"
  | "no-matching-version"
  | "empty-guard"
  | "guard-field-not-input"
  | "duplicate-guard"
  | "invalid-quota"
  | "quota-inverted"
  | "invalid-retry"
  | "retry-needs-idempotency"
  | "retry-forbidden"
  | "cache-missing-key"
  | "cache-missing-tenant"
  | "invalid-cache-ttl"
  | "invalid-feedback-channel";

export interface ContractIssue {
  consumer: string;
  capability: string;
  code: ContractIssueCode;
  detail: string;
}

const FEEDBACK = /^(issue|mailto|chat):\S+$/;
const RETRYABLE: readonly FailureMode[] = ["retry-safe", "retry-idempotent"];

export function validateConsumerContract(
  entry: CapabilityEntry,
  contract: ConsumerContract,
): ContractIssue[] {
  const issues: ContractIssue[] = [];
  const add = (code: ContractIssueCode, detail: string): void => {
    issues.push({ consumer: contract.consumer, capability: contract.capability, code, detail });
  };
  if (contract.consumer.trim() === "") add("missing-consumer", "consumer is empty");
  if (contract.capability !== entry.id) {
    add("unknown-capability", `entry is ${entry.id}, contract names ${contract.capability}`);
  }
  if (!isValidRange(contract.versionRange)) {
    add("invalid-range", `bad range ${contract.versionRange}`);
  } else if (!satisfiesRange(entry.version, contract.versionRange)) {
    add("no-matching-version", `${entry.version} is outside ${contract.versionRange}`);
  }
  const guardFields = new Set<string>();
  for (const guard of contract.inputGuards) {
    if (guard.field.trim() === "") add("empty-guard", "guard has no field");
    if (!entry.contract.inputs.includes(guard.field)) {
      add("guard-field-not-input", `${guard.field} is not a declared input`);
    }
    if (!Number.isInteger(guard.maxBytes) || guard.maxBytes <= 0) {
      add("empty-guard", `bad maxBytes ${guard.maxBytes} for ${guard.field}`);
    }
    if (guardFields.has(guard.field)) add("duplicate-guard", guard.field);
    guardFields.add(guard.field);
  }
  const quota = contract.quota;
  if (!Number.isInteger(quota.monthlyMicros) || !Number.isInteger(quota.perRequestMicros)
    || quota.monthlyMicros <= 0 || quota.perRequestMicros <= 0) {
    add("invalid-quota", `monthly=${quota.monthlyMicros} request=${quota.perRequestMicros}`);
  } else if (quota.perRequestMicros > quota.monthlyMicros) {
    add("quota-inverted", "per-request cap exceeds the monthly pool");
  }
  const retry = contract.retry;
  if (!Number.isInteger(retry.attempts) || retry.attempts < 0 || retry.attempts > 3) {
    add("invalid-retry", `attempts ${retry.attempts}`);
  }
  if (!Number.isInteger(retry.backoffMs) || retry.backoffMs < 0) {
    add("invalid-retry", `backoff ${retry.backoffMs}`);
  }
  if (retry.attempts > 0 && !RETRYABLE.includes(entry.failure)) {
    add("retry-forbidden", `${entry.failure} does not allow automatic retries`);
  }
  if (retry.attempts > 0 && entry.failure === "retry-idempotent" && !retry.idempotencyKey) {
    add("retry-needs-idempotency", "retry requires a consumer-generated idempotency key");
  }
  const cache = contract.cache;
  if (!Number.isInteger(cache.ttlSeconds) || cache.ttlSeconds < 0) {
    add("invalid-cache-ttl", `ttl ${cache.ttlSeconds}`);
  }
  if (!cache.key.includes("tenantId")) {
    add("cache-missing-tenant", "cache key must scope by tenantId");
  }
  if (new Set(cache.key).size !== cache.key.length) {
    add("cache-missing-key", "cache key has duplicate fields");
  }
  for (const field of entry.contract.cacheKey) {
    if (!cache.key.includes(field)) add("cache-missing-key", `cache key omits ${field}`);
  }
  if (!FEEDBACK.test(contract.feedbackChannel)) {
    add("invalid-feedback-channel", `bad channel ${contract.feedbackChannel}`);
  }
  return issues;
}

export interface OverrideRequest {
  param: string;
  value: string | number;
}

export type OverrideIssueCode = "unknown-override" | "value-not-allowed" | "duplicate-override";

export interface OverrideIssue {
  param: string;
  code: OverrideIssueCode;
  detail: string;
}

export interface OverrideDecision {
  param: string;
  value: string | number;
  /** Who owns quality and cost after the override is applied. */
  responsibility: Responsibility;
}

export interface OverrideResolution {
  ok: boolean;
  decisions: OverrideDecision[];
  issues: OverrideIssue[];
}

/** Apply caller overrides and return the owner of each resulting value. */
export function resolveOverrides(
  entry: CapabilityEntry,
  requests: readonly OverrideRequest[],
): OverrideResolution {
  const decisions: OverrideDecision[] = [];
  const issues: OverrideIssue[] = [];
  const seen = new Set<string>();
  for (const request of requests) {
    const declared = entry.overridable.find((param) => param.name === request.param);
    if (declared === undefined) {
      issues.push({
        param: request.param, code: "unknown-override",
        detail: `${request.param} is fixed by ${entry.provider}`,
      });
      continue;
    }
    if (seen.has(request.param)) {
      issues.push({
        param: request.param, code: "duplicate-override", detail: "declared twice",
      });
      continue;
    }
    seen.add(request.param);
    if (!declared.allowed.includes(request.value)) {
      issues.push({
        param: request.param, code: "value-not-allowed",
        detail: `${request.value} not in ${declared.allowed.join(",")}`,
      });
      continue;
    }
    decisions.push({
      param: request.param, value: request.value, responsibility: declared.responsibility,
    });
  }
  return { ok: issues.length === 0, decisions, issues };
}

export interface CommitmentSummary {
  availabilityPct: number;
  p95LatencyMs: number;
  billingUnit: BillingUnit;
  failure: FailureMode;
  retryable: boolean;
}

/** Provider-side summary; consumers must not restate these numbers locally. */
export function describeCommitment(entry: CapabilityEntry): CommitmentSummary {
  return {
    availabilityPct: Math.round(entry.sla.availability * 10000) / 100,
    p95LatencyMs: entry.sla.p95LatencyMs,
    billingUnit: entry.billingUnit,
    failure: entry.failure,
    retryable: RETRYABLE.includes(entry.failure),
  };
}