@fourier-labs/harbour-contracts 0.4.0 → 0.5.0

package/dist/gen-ts/ai-callsite-inventory.d.ts

@@ -0,0 +1,49 @@
+export type AiInventoryIdentifier = string;
+export type AiInventoryDigest = string;
+/**
+ * Immutable, sanitized AI call-site discovery for one exact Harbour deployment version. Inventory records detection only; planning, transformation, and verification outcomes are separate append-only records.
+ */
+export interface AiCallsiteInventory {
+    schema: 'harbour.ai-callsite-inventory/1.0';
+    tenantId: AiInventoryIdentifier;
+    appId: AiInventoryIdentifier;
+    environment: AiInventoryIdentifier;
+    versionId: string;
+    sourceRevision: string;
+    analyzerVersion: string;
+    coverage: 'complete_for_supported_sdks' | 'partial';
+    /**
+     * Required and never defaulted. Unavailable security evidence is not represented as a clean scan.
+     */
+    scanStatus: 'completed' | 'cybersecurity_scan_unavailable';
+    /**
+     * Canonical order is ascending by fingerprint, then path, then line. Producers MUST serialize this order before digesting or publishing the inventory.
+     *
+     * @maxItems 1000
+     */
+    callsites: AiInventoryCallsite[];
+}
+export interface AiInventoryCallsite {
+    fingerprint: AiInventoryDigest;
+    path: string;
+    sourceFileSha256: AiInventoryDigest;
+    line: number;
+    language: 'javascript' | 'typescript' | 'python' | 'go' | 'unknown';
+    sdk: 'openai' | 'openai-compatible' | 'anthropic' | 'google-genai' | 'mistral' | 'bedrock' | 'cohere' | 'ollama' | 'legacy-gemini' | 'direct-provider-rest' | 'unknown';
+    method: string;
+    requestedModel?: string;
+    strategy: 'deployment_injection' | 'deterministic_adapter' | 'unsupported';
+    status: 'detected';
+    /**
+     * @maxItems 64
+     */
+    securityFindingIds: string[];
+    evidence: AiInventoryEvidence;
+}
+export interface AiInventoryEvidence {
+    fingerprint: AiInventoryDigest;
+    /**
+     * Sanitized single-line evidence; never raw source or a prompt.
+     */
+    excerpt: string;
+}

package/dist/gen-ts/ai-gateway-key-lookup.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Value-free Gateway authentication metadata for one version-scoped Harbour key.
+ */
+export type AiGatewayKeyLookup = {
+    schema: 'harbour.ai-gateway-key-lookup/1.0';
+    keyId: string;
+    tenantId: AiGatewayKeyIdentifier;
+    appId: AiGatewayKeyIdentifier;
+    environment: AiGatewayKeyIdentifier;
+    versionId: string;
+    tokenPrefix: 'hbr_live_' | 'hbr_test_';
+    status: 'PENDING' | 'ACTIVE' | 'REVOKED';
+    keyMac?: string;
+    createdAt: string;
+    activatedAt?: string;
+    expiresAt?: string;
+    overlapExpiresAt?: string;
+    revokedAt?: string;
+};
+export type AiGatewayKeyIdentifier = string;

package/dist/gen-ts/ai-gateway-key-token.d.ts

@@ -0,0 +1,4 @@
+export declare const AiGatewayKeyProductionPrefix: "hbr_live_";
+export declare const AiGatewayKeyNonProductionPrefix: "hbr_test_";
+export declare const AiGatewayKeyTokenPatternSource: "^hbr_(live|test)_([0-9a-f]{32})\\.([A-Za-z0-9_-]{43})$";
+export declare const AiGatewayKeyTokenPattern: RegExp;

package/dist/gen-ts/ai-gateway-key-token.js

@@ -0,0 +1,6 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export const AiGatewayKeyProductionPrefix = "hbr_live_";
+export const AiGatewayKeyNonProductionPrefix = "hbr_test_";
+export const AiGatewayKeyTokenPatternSource = "^hbr_(live|test)_([0-9a-f]{32})\\.([A-Za-z0-9_-]{43})$";
+export const AiGatewayKeyTokenPattern = new RegExp(AiGatewayKeyTokenPatternSource);

package/dist/gen-ts/ai-governance-decision.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Digest-bound PLAN or VERIFY decision returned to the deployment control plane.
+ */
+export type AiGovernanceDecision = {
+    schema: 'harbour.ai-governance-decision/1.0';
+    phase: 'PLAN' | 'VERIFY';
+    tenantId: AiDecisionIdentifier;
+    appId: AiDecisionIdentifier;
+    environment: AiDecisionIdentifier;
+    versionId: string;
+    sourceRevision: string;
+    decision: 'PASS' | 'BLOCKED';
+    interceptionPath: 'NO_AI_CALLS' | 'DEPLOYMENT_INJECTION' | 'DETERMINISTIC_ADAPTER' | 'BLOCKED';
+    /**
+     * @maxItems 64
+     */
+    reasonCodes: AiDecisionIdentifier[];
+    /**
+     * @maxItems 1000
+     */
+    uncoveredCallsiteFingerprints: AiDecisionDigest[];
+    inventoryDigest: AiDecisionDigest;
+    policyDigest: AiDecisionDigest;
+    runtimeContractDigest?: AiDecisionDigest;
+    /**
+     * @maxItems 1000
+     */
+    interceptionPlan: AiInterceptionPlanEntry[];
+    interceptionPlanDigest: AiDecisionDigest;
+    evidenceDigest?: AiDecisionDigest;
+    runtimeContract?: AiDecisionRuntimeContract;
+    decidedAt: string;
+};
+export type AiDecisionIdentifier = string;
+export type AiDecisionDigest = string;
+export type AiInterceptionPlanEntry = {
+    callSiteFingerprint: AiDecisionDigest;
+    sourcePath: string;
+    expectedSourceFileSha256: AiDecisionDigest;
+    strategy: 'deployment_injection' | 'deterministic_adapter';
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    allowedSyntaxKinds: [AiDecisionIdentifier, ...AiDecisionIdentifier[]];
+    configurationMappingId?: AiDecisionIdentifier;
+    configurationMappingVersion?: string;
+    transformId?: AiDecisionIdentifier;
+    transformVersion?: string;
+    runtimeShimName?: string;
+    runtimeShimVersion?: string;
+    runtimeShimDigest?: AiDecisionDigest;
+};
+export interface AiDecisionRuntimeContract {
+    schema: 'harbour.ai-runtime-contract/1.0';
+    tenantId: AiDecisionIdentifier;
+    appId: AiDecisionIdentifier;
+    environment: AiDecisionIdentifier;
+    versionId: string;
+    sourceRevision: string;
+    mode: 'observe' | 'enforce';
+    gatewayBaseUrl: string;
+    gatewayKeySecretRef: string;
+    modelAliases: {
+        generation?: string;
+        embeddings?: string;
+    };
+    policyDigest: AiDecisionDigest;
+    /**
+     * @minItems 1
+     * @maxItems 2
+     */
+    requiredStrategies: ['deployment_injection' | 'deterministic_adapter'] | ['deployment_injection' | 'deterministic_adapter', 'deployment_injection' | 'deterministic_adapter'];
+}

package/dist/gen-ts/ai-policy-snapshot.d.ts

@@ -0,0 +1,429 @@
+export type AiPolicyScope = {
+    level: 'tenant' | 'application_environment';
+    tenantId: AiPolicyIdentifier;
+    appId?: AiPolicyIdentifier;
+    environment?: AiPolicyIdentifier;
+};
+export type AiPolicyIdentifier = string;
+export type AiPolicyDigest = string;
+export type AiPolicyGuardrailRule = {
+    ruleId: AiPolicyIdentifier;
+    detectorId: AiPolicyIdentifier;
+    detectorVersion: string;
+    phase: 'input' | 'output';
+    action: 'ALLOW' | 'OBSERVE' | 'REDACT' | 'BLOCK';
+    parameters?: AiPolicyGuardrailParameters;
+};
+/**
+ * Bounded, closed JSON Schema subset carried by an output.json_schema guardrail. Every node is a closed object over an enumerated keyword set; object nodes must state additionalProperties: false, so the validated output shape is closed too. Size is bounded per node (maxProperties/maxLength/maxItems); the consuming validator additionally enforces an overall byte budget at policy load.
+ */
+export type AiPolicyEmbeddedJsonSchema = {
+    type: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    description?: string;
+    properties?: {
+        [k: string]: AiPolicyEmbeddedJsonSchema;
+    };
+    /**
+     * @maxItems 64
+     */
+    required?: string[];
+    additionalProperties?: false;
+    items?: AiPolicyEmbeddedJsonSchema;
+    /**
+     * @minItems 1
+     * @maxItems 64
+     */
+    enum?: [string | number | number | boolean | null, ...(string | number | number | boolean | null)[]];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+};
+/**
+ * Immutable, content-addressed AI policy snapshot consumed by the Harbour AI Gateway. Provider credentials are represented only by Secrets Manager references.
+ */
+export interface AiPolicySnapshot {
+    schema: 'harbour.ai-policy-snapshot/1.0';
+    scope: AiPolicyScope;
+    revision: number;
+    publishedAt: string;
+    contentDigest: AiPolicyDigest;
+    baselineDigest: AiPolicyDigest;
+    classificationMinimum?: AiPolicyClassificationMinimum;
+    /**
+     * @maxItems 64
+     */
+    providers: AiPolicyProvider[];
+    /**
+     * @maxItems 512
+     */
+    models: AiPolicyModel[];
+    /**
+     * @maxItems 256
+     */
+    routes: AiPolicyRoute[];
+    /**
+     * @maxItems 256
+     */
+    policies: AiPolicyRuleSet[];
+    /**
+     * @maxItems 128
+     */
+    limits: AiPolicyLimit[];
+    retention: AiPolicyRetention;
+}
+export interface AiPolicyClassificationMinimum {
+    classification: 'Green' | 'Yellow' | 'Orange' | 'Red';
+    mappingDigest: AiPolicyDigest;
+}
+export interface AiPolicyProvider {
+    id: AiPolicyIdentifier;
+    provider: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+    baseUrl?: string;
+    credentialSecretRef: string;
+    enabled: boolean;
+}
+export interface AiPolicyModel {
+    id: AiPolicyIdentifier;
+    providerId: AiPolicyIdentifier;
+    providerModel: string;
+    /**
+     * @minItems 1
+     * @maxItems 2
+     */
+    capabilities: ['generation' | 'embeddings'] | ['generation' | 'embeddings', 'generation' | 'embeddings'];
+    approved: boolean;
+    pricing: AiPolicyPricing;
+}
+export interface AiPolicyPricing {
+    revision: AiPolicyIdentifier;
+    inputMicroUsdPerMillion: number;
+    outputMicroUsdPerMillion: number;
+}
+export interface AiPolicyRoute {
+    alias: AiPolicyIdentifier;
+    version: number;
+    capability: 'generation' | 'embeddings';
+    /**
+     * @minItems 1
+     * @maxItems 16
+     */
+    targets: [AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ] | [
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget,
+        AiPolicyRouteTarget
+    ];
+    retryCount: number;
+    timeoutMs: number;
+}
+export interface AiPolicyRouteTarget {
+    modelId: AiPolicyIdentifier;
+    priority: number;
+    weight: number;
+}
+export interface AiPolicyRuleSet {
+    name: AiPolicyIdentifier;
+    version: number;
+    maxRequestBytes: number;
+    maxInputTokens: number;
+    maxOutputTokens: number;
+    bufferedDelivery: boolean;
+    permittedRequestFields: AiPolicyPermittedRequestFields;
+    /**
+     * @maxItems 128
+     */
+    guardrails: AiPolicyGuardrailRule[];
+}
+export interface AiPolicyPermittedRequestFields {
+    temperature: boolean;
+    maxOutputTokens: boolean;
+    responseFormat: boolean;
+    tools: boolean;
+}
+export interface AiPolicyGuardrailParameters {
+    /**
+     * @minItems 1
+     * @maxItems 64
+     */
+    allowedTools?: [string, ...string[]];
+    jsonSchema?: AiPolicyEmbeddedJsonSchema;
+    jsonSchemaRef?: AiPolicyDigest;
+}
+export interface AiPolicyLimit {
+    name: AiPolicyIdentifier;
+    enabled: boolean;
+    scope: 'tenant' | 'application';
+    requestsPerMinute: number;
+    tokensPerMinute: number;
+    monthlyBudgetMicroUsd: number;
+}
+export interface AiPolicyRetention {
+    captureMode: 'OFF' | 'BEST_EFFORT' | 'REQUIRED';
+    retentionDays: number;
+    /**
+     * @maxItems 16
+     */
+    revealRoles: [] | [AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ] | [
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier,
+        AiPolicyIdentifier
+    ];
+}

package/dist/gen-ts/ai-runtime-contract.d.ts

@@ -0,0 +1,27 @@
+export type AiRuntimeIdentifier = string;
+export type AiRuntimeModelAlias = string;
+export type AiRuntimeDigest = string;
+/**
+ * Immutable deployment runtime contract derived by an AI Governance PLAN decision. Contains only scoped configuration and a Secrets Manager reference, never key plaintext.
+ */
+export interface AiRuntimeContract {
+    schema: 'harbour.ai-runtime-contract/1.0';
+    tenantId: AiRuntimeIdentifier;
+    appId: AiRuntimeIdentifier;
+    environment: AiRuntimeIdentifier;
+    versionId: string;
+    sourceRevision: string;
+    mode: 'observe' | 'enforce';
+    gatewayBaseUrl: string;
+    gatewayKeySecretRef: string;
+    modelAliases: {
+        generation?: AiRuntimeModelAlias;
+        embeddings?: AiRuntimeModelAlias;
+    };
+    policyDigest: AiRuntimeDigest;
+    /**
+     * @minItems 1
+     * @maxItems 2
+     */
+    requiredStrategies: ['deployment_injection' | 'deterministic_adapter'] | ['deployment_injection' | 'deterministic_adapter', 'deployment_injection' | 'deterministic_adapter'];
+}

package/dist/gen-ts/ai-trace-event.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Value-free asynchronous AI Gateway trace metadata. Raw prompts and responses never enter the queue; captured content is referenced only after successful encrypted storage.
+ */
+export type AiTraceEvent = {
+    schema: 'harbour.ai-trace-event/1.0';
+    traceId: string;
+    requestId: string;
+    tenantId: AiTraceIdentifier;
+    appId: AiTraceIdentifier;
+    environment: AiTraceIdentifier;
+    versionId: string;
+    callsiteFingerprint?: AiTraceDigest;
+    policyDigest: AiTraceDigest;
+    routeRevision?: string;
+    requestedModel?: string;
+    governedModelAlias?: string;
+    provider?: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+    providerModel?: string;
+    outcome: 'succeeded' | 'blocked' | 'failed' | 'cancelled';
+    usage?: AiTraceUsage;
+    priceRevision?: AiTraceIdentifier;
+    costMicroUsd: number;
+    latencyMs: number;
+    retryCount: number;
+    fallbackUsed: boolean;
+    reservationId?: string;
+    /**
+     * @minItems 0
+     * @maxItems 32
+     */
+    attempts: AiTraceAttempt[];
+    /**
+     * @maxItems 128
+     */
+    guardrailResults: AiTraceGuardrailResult[];
+    contentCaptureStatus: 'off' | 'captured' | 'capture_failed';
+    contentRef?: string;
+    retentionExpiresAt?: string;
+    occurredAt: string;
+};
+export type AiTraceIdentifier = string;
+export type AiTraceDigest = string;
+export type AiTraceAttempt = {
+    attempt: number;
+    provider: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+    providerModel: string;
+    priceRevision: AiTraceIdentifier;
+    outcome: 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+    /**
+     * Provider-reported token usage, or null when the attempt did not succeed and the provider reported none. Null states that usage is UNKNOWN — estimates are never fabricated. A succeeded attempt always reports real usage.
+     */
+    usage: AiTraceUsage | null;
+    costMicroUsd: number;
+    latencyMs: number;
+    errorCode?: string;
+};
+export interface AiTraceUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface AiTraceGuardrailResult {
+    ruleId: string;
+    detectorId: string;
+    detectorVersion: string;
+    phase: 'input' | 'output';
+    action: 'ALLOW' | 'OBSERVE' | 'REDACT' | 'BLOCK';
+    result: 'passed' | 'matched' | 'blocked' | 'redacted';
+}