/** * src/schema/record-schema.ts * ============================ * P063: the schema 0pt versions per source, and the compatibility policy that * governs what the next version may change. * * Deliberately a SMALL structural schema (field name -> type + required), not * a second JSON-Schema dialect: 0pt already ships JSON Schema in * packages/schemas/ for its own contracts, and Zod in src/validation for HTTP * bodies. Neither of those answers the question P063 actually asks — "is * version N+1 of an UPSTREAM source's record shape safe for the consumers * reading version N?" — which needs a comparable, field-level structure, not * a validator. Anything richer belongs in a real schema registry * (Confluent/Apicurio) and would be an integration, not a rewrite of this. */ export type FieldType = "string" | "number" | "boolean" | "timestamp" | "object" | "array"; export interface FieldSpec { type: FieldType; required: boolean; } /** A record shape: field name -> spec. */ export type RecordSchemaFields = Record; /** * Compatibility policy, using the standard schema-registry vocabulary: * * - `backward` — new readers can read data written under the OLD schema. * Safe: adding an optional field, removing an optional field, relaxing a * required field to optional. Breaking: adding a REQUIRED field, removing * a field an old writer still emits as required, changing a type. * - `forward` — old readers can read data written under the NEW schema. * Safe: adding a required field, removing an optional field. Breaking: * removing a REQUIRED field, changing a type. * - `full` — both of the above. * - `none` — no check. Recorded, never silently assumed: a source must * declare `none` explicitly, and the runner logs it as an accepted risk. */ export type CompatibilityPolicy = "backward" | "forward" | "full" | "none"; export interface RecordSchema { source_id: string; tenant_id: string; schema_version: number; fields: RecordSchemaFields; compatibility: CompatibilityPolicy; registered_at: string; registered_by?: string; } /** One incompatibility between two schema versions. */ export interface SchemaBreak { field: string; /** Which direction the change breaks. */ breaks: "backward" | "forward"; detail: string; } export interface CompatibilityVerdict { compatible: boolean; policy: CompatibilityPolicy; breaks: SchemaBreak[]; }