/**
 * @traffical/sdk-spec
 * 
 * Type definitions for Traffical SDK specifications.
 */

import type { JSONSchema7 } from 'json-schema';

// Schema types
export declare const configBundleSchema: JSONSchema7;
export declare const eventsSchema: JSONSchema7;
export declare const trafficalConfigSchema: JSONSchema7;

// Test vector bundle types
//
// Mirrors the real `ConfigBundle` shape defined in
// schemas/config-bundle.schema.json and used by the fixtures:
// - `version` is an ISO date-time string (not a number)
// - `parameters` is an array of {key,type,default,layerId,namespace} (not a map)
// - allocations carry `overrides` (not `parameters`) and an optional `id`
// - conditions use {field,op,value,values} (not {type,field,operator,value})
// - layers have no `priority`; policies carry state/kind and optional
//   entityConfig / eligibleBucketRange / contextualModel
export interface TestBundle {
  version: string;
  orgId: string;
  projectId: string;
  env: string;
  hashing: {
    unitKey: string;
    bucketCount: number;
    algorithm?: 'sha256-v2';
  };
  parameters: Array<{
    key: string;
    type: 'string' | 'number' | 'boolean' | 'json';
    default: unknown;
    layerId: string;
    namespace: string;
  }>;
  layers: Array<{
    id: string;
    unitKey?: string;
    policies: Array<{
      id: string;
      state: 'draft' | 'running' | 'paused' | 'completed';
      kind: 'static' | 'adaptive';
      allocations: Array<{
        id?: string;
        /** Display only — never an identifier. See `key`. */
        name: string;
        /** Stable identifier; the join key. Absent only in pre-`key` bundles. */
        key?: string;
        bucketRange: [number, number];
        overrides: Record<string, unknown>;
      }>;
      conditions: Array<{
        field: string;
        op: string;
        value?: unknown;
        values?: unknown[];
      }>;
      stateVersion?: string;
      eligibleBucketRange?: [number, number];
      entityConfig?: {
        entityKeys: string[];
        resolutionMode: 'bundle' | 'edge';
        dynamicAllocations?: { countKey: string };
      };
      contextLogging?: { allowedFields: string[] };
      contextualModel?: unknown;
    }>;
  }>;
}

export interface ExpectedResults {
  description: string;
  testCases: Array<{
    name: string;
    context: Record<string, unknown>;
    expectedHashing?: Record<string, {
      input: string;
      bucket: number;
    }>;
    expectedAssignments: Record<string, unknown>;
  }>;
}

export declare const bundleBasic: TestBundle;
export declare const bundleConditions: TestBundle;
export declare const bundleEdgePolicies: TestBundle;
export declare const bundleContextual: TestBundle;
export declare const bundlePerLayerUnitKey: TestBundle;
export declare const bundleUnicode: TestBundle;
export declare const bundleContextualBoundary: TestBundle;
// 0.7.0 drift-remediation fixtures
export declare const bundleEmptyUnitKey: TestBundle;
export declare const bundleNumericUnitKey: TestBundle;
export declare const bundleContextualGammaZero: TestBundle;
export declare const bundleContextualHighFloor: TestBundle;
export declare const bundleConditionsOmitted: TestBundle;
export declare const expectedBasic: ExpectedResults;
export declare const expectedConditions: ExpectedResults;

// UTF-8 byte-hashing conformance (bundle_unicode / expected_unicode).
export interface ExpectedUnicodeResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    comment?: string;
    context: Record<string, unknown>;
    expectedHashing: Record<string, { bucket: number }>;
    expectedAssignments: Record<string, unknown>;
  }>;
}

export declare const expectedUnicode: ExpectedUnicodeResults;

export interface ExpectedContextualResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    context: Record<string, unknown>;
    expectedScoring: {
      scores: number[];
      seed: string;
      comment: string;
    };
    expectedAssignments: Record<string, unknown>;
    expectedAllocation: string;
  }>;
}

export declare const expectedContextual: ExpectedContextualResults;

// Near-gridline contextual softmax conformance
// (bundle_contextual_boundary / expected_contextual_boundary).
export interface ExpectedContextualBoundaryResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    comment?: string;
    context: Record<string, unknown>;
    expectedScoring: {
      scores: number[];
      probabilities?: number[];
      seed: string;
      selectedIndex?: number;
      comment?: string;
    };
    expectedAllocation: string;
    expectedAssignments: Record<string, unknown>;
  }>;
}

export declare const expectedContextualBoundary: ExpectedContextualBoundaryResults;

// S6 numerical guards: gamma=0 (safeGamma) and floor>1/n (effectiveFloor).
// Same scoring shape as the boundary fixture.
export declare const expectedContextualGammaZero: ExpectedContextualBoundaryResults;
export declare const expectedContextualHighFloor: ExpectedContextualBoundaryResults;

export interface ExpectedPerLayerUnitKeyResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    comment?: string;
    context: Record<string, unknown>;
    expectedHashing: Record<string, {
      unitKeyValue?: string;
      bucket: number;
      comment?: string;
    }>;
    expectedAssignments: Record<string, unknown>;
    expectedLayers: Array<{
      layerId: string;
      bucket: number;
      policyId?: string;
      allocationName?: string;
      unitKey?: string;
      unitKeyValue?: string;
      comment?: string;
    }>;
  }>;
}

export declare const expectedPerLayerUnitKey: ExpectedPerLayerUnitKeyResults;

// S1: empty/whitespace layer unitKey override -> skip the layer (bucket -1).
// S2: canonical Number::toString stringification of numeric unit keys.
// Both reuse the per-layer-unit-key shape (expectedHashing + expectedLayers).
export declare const expectedEmptyUnitKey: ExpectedPerLayerUnitKeyResults;
export declare const expectedNumericUnitKey: ExpectedPerLayerUnitKeyResults;

// S5: relational op with omitted value never matches.
export interface ExpectedConditionsOmittedResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    comment?: string;
    context: Record<string, unknown>;
    expectedAssignments: Record<string, unknown>;
    expectedLayers: Array<{
      layerId: string;
      bucket?: number;
      policyId?: string;
      allocationName?: string;
      comment?: string;
    }>;
  }>;
}

export declare const expectedConditionsOmitted: ExpectedConditionsOmittedResults;

// S10: allocation identity — `key` is the identifier, `name` is display-only.
// Coefficients resolve by `key ?? name`; every allocation in the primary policy
// has a name that differs from its key, and a second policy carries no `key` at
// all to pin the fallback. `expectedPolicies` is keyed by policy id because the
// bundle resolves more than one policy per decision.
export interface ExpectedContextualKeyDiffersResults {
  description: string;
  bundle: string;
  testCases: Array<{
    name: string;
    context: Record<string, unknown>;
    expectedAssignments: Record<string, unknown>;
    expectedPolicies: Record<
      string,
      {
        allocationName: string;
        allocationKey?: string;
        scores?: number[];
        probabilities?: number[];
        selectedIndex?: number;
        seed?: string;
        comment?: string;
      }
    >;
  }>;
}

export declare const bundleContextualKeyDiffers: TestBundle;
export declare const expectedContextualKeyDiffers: ExpectedContextualKeyDiffersResults;

// S4: exposure-event SHAPE conformance for trackExposure(). Given a decision's
// resolved layers + in-session dedup state, the exact exposure events emitted.
export interface ExposureShapeFixture {
  description: string;
  schema: string;
  dedupKey: string;
  testCases: Array<{
    name: string;
    comment?: string;
    unitKey: string;
    configVersion?: string;
    assignments: Record<string, unknown>;
    resolvedLayers: Array<Record<string, unknown>>;
    alreadyExposed: Array<{ layerId: string; allocationName: string }>;
    expectedEvents: Array<Record<string, unknown>>;
  }>;
}

export declare const exposureShape: ExposureShapeFixture;

export interface EdgeResultEntry {
  policyId: string;
  allocationIndex: number;
  entityId: string;
}

export interface ExpectedEdgePoliciesResults {
  description: string;
  bundle: string;
  entityWeights: string;
  testCases: Array<{
    name: string;
    comment?: string;
    context: Record<string, unknown>;
    defaults: Record<string, unknown>;
    edgeResults: EdgeResultEntry[];
    expectedAssignments: Record<string, unknown>;
    expectedLayers: Array<Record<string, unknown>>;
  }>;
}

export interface ExpectedResolveResults {
  description: string;
  bundle: string;
  entityWeights: string;
  testCases: Array<{
    name: string;
    comment?: string;
    request: {
      context: Record<string, unknown>;
      parameters?: string[];
    };
    expectedEdgeResults: EdgeResultEntry[];
    expectedAssignments: Record<string, unknown>;
    expectedLayers: Array<Record<string, unknown>>;
  }>;
}

export interface EntityWeightsFixture {
  [policyId: string]: {
    _global: { entityId: string; weights: number[]; computedAt: string };
    entities: Record<string, { entityId: string; weights: number[]; computedAt: string }>;
  };
}

export declare const expectedEdgePolicies: ExpectedEdgePoliciesResults;
export declare const expectedResolve: ExpectedResolveResults;
export declare const entityWeights: EntityWeightsFixture;

export interface EventsConformanceFixture {
  description: string;
  schema: string;
  testCases: Array<{
    name: string;
    valid: boolean;
    comment?: string;
    event: Record<string, unknown>;
  }>;
}

export declare const eventsConformance: EventsConformanceFixture;

// Path exports
export declare const schemaPaths: {
  configBundle: string;
  events: string;
  trafficalConfig: string;
};

export declare const testVectorPaths: {
  bundleBasic: string;
  bundleConditions: string;
  bundleEdgePolicies: string;
  bundleContextual: string;
  expectedBasic: string;
  expectedConditions: string;
  expectedEdgePolicies: string;
  expectedResolve: string;
  expectedContextual: string;
  bundlePerLayerUnitKey: string;
  expectedPerLayerUnitKey: string;
  bundleUnicode: string;
  expectedUnicode: string;
  bundleContextualBoundary: string;
  expectedContextualBoundary: string;
  bundleEmptyUnitKey: string;
  expectedEmptyUnitKey: string;
  bundleNumericUnitKey: string;
  expectedNumericUnitKey: string;
  bundleContextualGammaZero: string;
  expectedContextualGammaZero: string;
  bundleContextualHighFloor: string;
  expectedContextualHighFloor: string;
  bundleConditionsOmitted: string;
  expectedConditionsOmitted: string;
  bundleContextualKeyDiffers: string;
  expectedContextualKeyDiffers: string;
  entityWeights: string;
  eventsConformance: string;
  exposureShape: string;
};