TypeScript Types

The AIPC runtime ships with full TypeScript type definitions. These types mirror the JSON Schema and provide compile-time safety when building runtimes, providers, or tools.

Core types

AIPCResponse

The top-level type for any AIPC-wrapped API response:

interface AIPCResponse {
  aipc_version: string;
  provider: Provider;
  contract: Contract;
  payload: Record<string, any>;
}

Provider

interface Provider {
  id: string;
  name: string;
  authority?: string;
  contract_version: string;
  contact?: string;
  terms_url?: string;
  logo?: {
    url: string;
    display: "required" | "optional";
    min_height_px?: number;
  };
}

Contract

interface Contract {
  disclosures: Disclosure[];
  display_rules: DisplayRule[];
  attribution: Attribution;
  freshness: Freshness;
  tone?: ToneDirective;
  conditional_rules?: ConditionalRule[];
  fail_behavior: "suppress" | "warn" | "partial" | "log";
  minimum_compliance_level?: "L1" | "L2" | "L3";
}

Disclosure

interface Disclosure {
  id: string;
  text: string;
  verbatim: boolean;
  scope: string[];
  placement: "before" | "after" | "adjacent" | "global";
  priority: "required" | "recommended" | "optional";
  language?: string;
  translations?: Record<string, string>;
  paraphrase_constraints?: {
    must_include_concepts: string[];
    max_words: number;
    tone: string;
  };
}

DisplayRule

interface DisplayRule {
  scope: string[];
  label?: {
    text: string;
    verbatim: boolean;
    alternatives?: string[];
  };
  format?: {
    type: "percentage" | "currency" | "number" | "date" | "ordinal_scale" | "categorical";
    precision?: number;
    rounding?: "half-even" | "half-up" | "floor" | "ceil";
    sign?: "always" | "negative-only";
    currency_field?: string;
    symbol_position?: "before" | "after";
    min?: number;
    max?: number;
    unit?: string;
    display_as?: string;
    grouping?: boolean;
    format?: string;
    timezone?: string;
  };
  context_required?: string[];
  never_show_without?: string[];
  suppress_if?: {
    field: string;
    operator: string;
    value: any;
  };
}

ValidatedOutput

Returned by AIPCRuntime.validate():

interface ValidatedOutput {
  success: boolean;
  compliance_level: "L1" | "L2" | "L3";
  provider: Provider;
  formatted_fields: FormattedField[];
  disclosures: {
    global: string[];
    before: Map<string, string[]>;
    after: Map<string, string[]>;
    adjacent: Map<string, string[]>;
  };
  attribution: string | null;
  attribution_link: string | null;
  freshness_status: "valid" | "stale" | "expired";
  freshness_warning: string | null;
  tone_restrictions: {
    prohibited_phrases: string[];
    prohibited_framings: string[];
    editorial_restrictions: Record<string, boolean>;
  };
  audit: AuditEntry;
  errors: string[];
  warnings: string[];
}

Renderer types

RenderedOutput

Returned by AIPCRenderer.render():

interface RenderedOutput {
  blocks: RenderedBlock[];
  narrativeContext: NarrativeContext;
  modality: "visual" | "voice" | "document";
  format: string;
}

RenderedBlock

interface RenderedBlock {
  type: "disclosure" | "data_point" | "data_table" | "attribution"
      | "freshness_warning" | "suppression_notice" | "conditional_notice";
  content: string;
  placement: "header" | "before_data" | "after_data" | "footer" | "inline";
  metadata: Record<string, any>;
}

NarrativeContext

interface NarrativeContext {
  dataSummary: string;
  referenceableFields: ReferenceableField[];
  toneRestrictions: {
    framing: string;
    prohibitedPhrases: string[];
    prohibitedFramings: string[];
    editorialRestrictions: Record<string, boolean>;
  };
  prohibitions: string[];
  suggestedScope: string;
}

ReferenceableField

interface ReferenceableField {
  path: string;
  label: string;
  formattedValue: string;
  unit?: string;
}

Validator types

ValidationResult

Returned by AIPCValidator.validate():

interface ValidationResult {
  passed: boolean;
  violations: Violation[];
  warnings: Warning[];
  checksRun: string[];
}

Violation

interface Violation {
  check: string;
  severity: "critical" | "major" | "minor";
  message: string;
  span?: { start: number; end: number };
  matchedText?: string;
}

Warning

interface Warning {
  check: string;
  message: string;
  suggestion?: string;
}

Compositor types

ComplianceEnforcedResponse

Returned by AIPCCompositor.enforce():

interface ComplianceEnforcedResponse {
  success: boolean;
  assembled: AssembledResponse;
  audit: ComplianceAudit;
  enforcementLevel: "L1" | "L2" | "L3";
  narrativeSuppressed: boolean;
}

AssembledResponse

interface AssembledResponse {
  plaintext: string;
  html: string;
  markdown: string;
  structured: ResponseSegment[];
}

ResponseSegment

interface ResponseSegment {
  type: "attribution" | "freshness_warning" | "disclosure" | "narrative"
      | "data_block" | "suppression_notice";
  content: string;
  position: number;
  source: "deterministic" | "llm" | "enforcement";
}

ComplianceAudit

interface ComplianceAudit {
  entries: {
    stage: "render" | "validate" | "enforce" | "assemble" | "audit";
    action: string;
    detail: string;
    timestamp: string;
  }[];
  violations: Violation[];
  retriesAttempted: number;
  suppressionReason?: string;
  enforcementLevel: "L1" | "L2" | "L3";
}

Importing types

import type {
  AIPCResponse,
  Contract,
  Disclosure,
  DisplayRule,
  ValidatedOutput,
  FormattedField,
  RenderedOutput,
  RenderedBlock,
  NarrativeContext,
  ReferenceableField,
  ValidationResult,
  Violation,
  Warning,
  ComplianceEnforcedResponse,
  AssembledResponse,
  ResponseSegment,
  ComplianceAudit,
} from '@aipc/runtime';