@plasius/schema 1.2.18 → 1.3.1

package/dist/feedback-diagnostics-BaniQAFS.d.cts

@@ -0,0 +1,353 @@
+import { FeedbackGameDiagnostics } from './feedback-diagnostics-vocabulary.cjs';
+
+type PIIClassification = "none" | "low" | "high";
+type PIIAction = "encrypt" | "hash" | "clear" | "none";
+type PIILogHandling = "redact" | "omit" | "pseudonym" | "plain";
+interface PII {
+    classification: PIIClassification;
+    action: PIIAction;
+    logHandling?: PIILogHandling;
+    purpose?: string;
+}
+
+interface ValidationIssueInput {
+    code: string;
+    message: string;
+    path?: string;
+}
+interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+type FieldValidatorResult = boolean | string | ValidationIssueInput | ValidationIssueInput[];
+type FieldValidator<T = unknown> = {
+    bivarianceHack(value: T): FieldValidatorResult;
+}["bivarianceHack"];
+
+type FieldType$1 = "string" | "number" | "boolean" | "object" | "array" | "ref";
+
+type FieldExposure = "public" | "internal";
+declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
+    type: FieldType$1;
+    _type: TExternal;
+    _storageType: TInternal;
+    isSystem: boolean;
+    isImmutable: boolean;
+    isRequired: boolean;
+    _validator?: FieldValidator<TInternal>;
+    _description: string;
+    _version: string;
+    _default?: TInternal | (() => TInternal);
+    _upgrade?: (value: any, ctx: {
+        entityFrom: string;
+        entityTo: string;
+        fieldTo: string;
+        fieldName: string;
+    }) => {
+        ok: boolean;
+        value?: any;
+        error?: string;
+    };
+    _shape?: Record<string, FieldBuilder<any>>;
+    itemType?: FieldBuilder<any>;
+    refType?: string;
+    _pii: PII;
+    _exposure: FieldExposure;
+    enumValues?: readonly TInternal[];
+    constructor(type: FieldType$1, options?: {
+        shape?: Record<string, FieldBuilder<any>>;
+        itemType?: FieldBuilder<any>;
+        refType?: string;
+    });
+    immutable(): FieldBuilder<TExternal, TInternal>;
+    system(): FieldBuilder<TExternal, TInternal>;
+    exposure(exposure: FieldExposure): FieldBuilder<TExternal, TInternal>;
+    internal(): FieldBuilder<TExternal, TInternal>;
+    public(): FieldBuilder<TExternal, TInternal>;
+    required(): FieldBuilder<TExternal, TInternal>;
+    optional(): FieldBuilder<TExternal, TInternal>;
+    validator(fn: FieldValidator<TInternal>): FieldBuilder<TExternal, TInternal>;
+    description(desc: string): FieldBuilder<TExternal, TInternal>;
+    default(value: TInternal | (() => TInternal)): FieldBuilder<TExternal, TInternal>;
+    /**
+     * Configure an upgrader used when validating older entities against a newer schema.
+     * The upgrader receives the current field value and version context, and should
+     * return { ok: true, value } with the upgraded value, or { ok: false, error }.
+     */
+    upgrade(fn: (value: any, ctx: {
+        entityFrom: string;
+        entityTo: string;
+        fieldTo: string;
+        fieldName: string;
+    }) => {
+        ok: boolean;
+        value?: any;
+        error?: string;
+    }): FieldBuilder<TExternal, TInternal>;
+    getDefault(): TInternal | undefined;
+    version(ver: string): FieldBuilder<TExternal, TInternal>;
+    PID(pii: PII): FieldBuilder<TExternal, TInternal>;
+    min(min: number): FieldBuilder<TExternal, TInternal>;
+    max(max: number): FieldBuilder<TExternal, TInternal>;
+    pattern(regex: RegExp): FieldBuilder<TExternal, TInternal>;
+    enum<const U extends readonly TInternal[]>(values: U): FieldBuilder<U[number]>;
+    /**
+     * Create a shallow clone with a different external type parameter.
+     * Note: shape and itemType are passed by reference (shallow). If you need
+     * deep isolation of nested FieldBuilders, clone them explicitly.
+     */
+    as<U>(): FieldBuilder<U, TInternal>;
+}
+
+type InferField<T> = T extends {
+    _type: infer U;
+} ? U : T extends {
+    type: "string";
+} ? string : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "array";
+    itemType: infer Item;
+} ? InferField<Item>[] : T extends {
+    type: "object";
+    shape: infer Shape extends SchemaShape;
+} ? InferFromShape<Shape> : unknown;
+type IsOptional<T> = T extends {
+    isRequired: false;
+} ? true : false;
+type InferFromShape<S extends SchemaShape> = {
+    [K in keyof S]: IsOptional<S[K]> extends true ? InferField<S[K]> | undefined : InferField<S[K]>;
+};
+type InferFromSchema<T extends {
+    shape: SchemaShape;
+}> = InferFromShape<T["shape"]>;
+type IsSchema<T> = T extends {
+    shape: SchemaShape;
+} ? true : false;
+type Infer<T> = IsSchema<T> extends true ? InferFromSchema<T & {
+    shape: SchemaShape;
+}> : InferFromShape<T & SchemaShape>;
+
+type FieldTypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    object: Record<string, unknown>;
+    "string[]": string[];
+    "number[]": number[];
+    "boolean[]": boolean[];
+    "object[]": Record<string, unknown>[];
+    ref: RefEntityId;
+    "ref[]": RefEntityId[];
+};
+type FieldType = keyof FieldTypeMap;
+type PIIEnforcement = "strict" | "warn" | "none";
+/** Supported unknown-field policies in backwards-compatible order. */
+declare const SCHEMA_UNKNOWN_FIELDS_POLICIES: readonly ["strip", "reject"];
+/** Controls whether fields outside a schema shape are stripped or rejected. */
+type UnknownFieldsPolicy = (typeof SCHEMA_UNKNOWN_FIELDS_POLICIES)[number];
+/** Supported schema-identity policies in backwards-compatible order. */
+declare const SCHEMA_IDENTITY_POLICIES: readonly ["compatible", "exact"];
+/** Controls exact enforcement of a schema's declared type and version. */
+type SchemaIdentityPolicy = (typeof SCHEMA_IDENTITY_POLICIES)[number];
+/** Result returned by a schema upgrade function. */
+type SchemaUpgradeResult = {
+    ok: boolean;
+    /** Upgraded entity (must include all required fields for the new schema). */
+    value?: Record<string, any>;
+    /** Optional human-readable errors if upgrade fails. */
+    errors?: string[];
+};
+/**
+ * A function that upgrades an entity from an older schema version to a newer one.
+ * It should be **pure** and not mutate its arguments.
+ */
+type SchemaUpgradeFunction = (input: Record<string, any>, ctx: {
+    from: string;
+    to: string;
+    entityType: string;
+    /** Describe function for the target schema – useful for dynamic migrations. */
+    describe: () => {
+        entityType: string;
+        version: string;
+        shape: Record<string, any>;
+    };
+    log?: (msg: string) => void;
+}) => SchemaUpgradeResult;
+type SchemaUpgradeStep = {
+    /** The target version this step upgrades to (e.g., "1.1.0"). */
+    to: string;
+    /** The migration function that upgrades from the previous step's version to `to`. */
+    run: SchemaUpgradeFunction;
+};
+/**
+ * Schema-level upgrade specification can be either:
+ *  - a single `SchemaUpgradeFunction` that handles any from->to, OR
+ *  - an ordered array of steps, each targeting a specific `to` version, which
+ *    will be applied sequentially to cascade from the oldest known version to the latest.
+ */
+type SchemaUpgradeSpec = SchemaUpgradeFunction | SchemaUpgradeStep[];
+/**
+ * Presence-only metadata supplied to a schema-level validator.
+ *
+ * Raw input values are intentionally withheld. `wasProvided` distinguishes
+ * an omitted optional field from an explicitly supplied `null`/`undefined`.
+ */
+interface SchemaValidationContext {
+    readonly wasProvided: (fieldName: string) => boolean;
+}
+interface SchemaOptions {
+    version?: string;
+    table?: string;
+    schemaValidator?: (value: any, context?: SchemaValidationContext) => boolean;
+    piiEnforcement?: PIIEnforcement;
+    /**
+     * How validation handles properties not declared by the schema.
+     *
+     * `strip` preserves the historical behaviour. `reject` is intended for
+     * trust boundaries where silently accepting extra data would be unsafe.
+     */
+    unknownFields?: UnknownFieldsPolicy;
+    /**
+     * `exact` rejects a mismatched `type` or `version` after any configured
+     * upgrade. The backwards-compatible default validates only their field
+     * shapes.
+     */
+    identity?: SchemaIdentityPolicy;
+    schemaUpgrade?: SchemaUpgradeStep[] | SchemaUpgradeFunction | undefined;
+}
+interface SerializeOptions {
+    includeInternal?: boolean;
+}
+type SchemaShape = Record<string, FieldBuilder<any>>;
+interface FieldDefinition<T = unknown> {
+    type: FieldType;
+    __valueType?: T;
+    optional?: boolean;
+    immutable?: boolean;
+    description?: string;
+    refType?: string;
+    version?: string;
+    deprecated?: boolean;
+    deprecatedVersion?: string;
+    system?: boolean;
+    autoValidate?: boolean;
+    refPolicy?: "eager" | "lazy";
+    enum?: string[];
+    _shape?: SchemaShape;
+    pii?: PII;
+    exposure?: FieldExposure;
+    validator?: FieldValidator<T>;
+}
+interface ValidateCompositionOptions {
+    resolveEntity: (type: string, id: string) => Promise<any | null>;
+    validatorContext?: {
+        visited: Set<string>;
+    };
+    maxDepth?: number;
+    log?: (msg: string) => void;
+    onlyFields?: string[];
+}
+interface Schema<T extends SchemaShape> {
+    _shape: T;
+    meta: {
+        entityType: string;
+        version: string;
+    };
+    schemaValidator: (entity: Infer<T>, context?: SchemaValidationContext) => boolean;
+    /**
+     * Runs the optional schema-level upgrade function once, without validating.
+     * Useful for offline migrations or testing migration logic.
+     */
+    upgrade(input: Record<string, any>, log?: (msg: string) => void): {
+        ok: boolean;
+        value?: Record<string, any>;
+        errors?: string[];
+    };
+    validate: (input: unknown, existing?: Record<string, any>) => ValidationResult<Infer<T>>;
+    validateComposition: (entity: Infer<T>, options: ValidateCompositionOptions) => Promise<void>;
+    serialize: (input: Record<string, any>, options?: SerializeOptions) => Record<string, any>;
+    tableName?: () => string | undefined;
+    prepareForRead(stored: Record<string, any>, decryptFn: (value: string) => any | null): Record<string, any>;
+    prepareForStorage(input: Record<string, any>, encryptFn: (value: any) => string, hashFn: (value: any) => string): Record<string, any>;
+    sanitizeForLog(data: Record<string, any>, pseudonymFn: (value: any) => string): Record<string, any>;
+    getPiiAudit(): Array<{
+        field: string;
+        classification: PIIClassification;
+        action: PIIAction;
+        logHandling?: PIILogHandling;
+        purpose?: string;
+    }> | null;
+    scrubPiiForDelete(stored: Record<string, any>): Record<string, any>;
+    describe(): {
+        entityType: string;
+        version: string;
+        shape: Record<string, {
+            type: FieldType;
+            optional: boolean;
+            immutable: boolean;
+            description: string;
+            version: string;
+            deprecated: boolean;
+            deprecatedVersion: string | null;
+            system: boolean;
+            enum: string[] | null;
+            refType: string | null;
+            pii: PII | null;
+            exposure: FieldExposure;
+        }>;
+    };
+}
+type DeepReadonly<T> = {
+    readonly [K in keyof T]: T[K] extends object ? T[K] extends (...args: any[]) => any ? T[K] : DeepReadonly<T[K]> : T[K];
+};
+interface ValidationResult<T> {
+    valid: boolean;
+    value?: DeepReadonly<T>;
+    errors?: string[];
+    issues?: ValidationIssue[];
+}
+type RefEntityId<T extends string = string> = {
+    type: T;
+    id: string;
+};
+
+/** Bucketed, consented renderer diagnostics; it cannot express pixels or DOM. */
+declare const FeedbackGameDiagnosticsSchema: Schema<{
+    surfaceId: FieldBuilder<"site.generator" | "site.gpu-demo", "site.generator" | "site.gpu-demo">;
+    consentConfirmed: FieldBuilder<boolean, boolean>;
+    provenanceContractId: FieldBuilder<"generator.renderer-diagnostics.v1" | "gpu-demo.renderer-diagnostics.v1", "generator.renderer-diagnostics.v1" | "gpu-demo.renderer-diagnostics.v1">;
+    renderer: FieldBuilder<"webgl2" | "webgpu" | "canvas2d" | "unknown", "webgl2" | "webgpu" | "canvas2d" | "unknown">;
+    backend: FieldBuilder<"unknown" | "browser" | "worker", "unknown" | "browser" | "worker">;
+    viewportBucket: FieldBuilder<"unknown" | "small-portrait" | "small-landscape" | "medium-portrait" | "medium-landscape" | "large-portrait" | "large-landscape", "unknown" | "small-portrait" | "small-landscape" | "medium-portrait" | "medium-landscape" | "large-portrait" | "large-landscape">;
+    frameRateBucket: FieldBuilder<"unknown" | "under-15" | "15-29" | "30-59" | "60-plus", "unknown" | "under-15" | "15-29" | "30-59" | "60-plus">;
+    frameTimeBucket: FieldBuilder<"unknown" | "under-17ms" | "17-33ms" | "34-66ms" | "over-66ms", "unknown" | "under-17ms" | "17-33ms" | "34-66ms" | "over-66ms">;
+    featureIds: FieldBuilder<unknown, unknown>;
+    counters: FieldBuilder<unknown, unknown>;
+    errorCodes: FieldBuilder<unknown, unknown>;
+    type?: FieldBuilder<"feedback-game-diagnostics", "feedback-game-diagnostics"> | undefined;
+    version?: FieldBuilder<"1.0.0", "1.0.0"> | undefined;
+}>;
+type FeedbackGameDiagnosticsValidationResult = {
+    readonly valid: true;
+    readonly value: FeedbackGameDiagnostics;
+    readonly errors?: never;
+    readonly issues?: never;
+} | {
+    readonly valid: false;
+    readonly value?: never;
+    readonly errors: readonly string[];
+    readonly issues?: readonly ValidationIssue[];
+};
+/**
+ * Validate and clone diagnostics while preserving the correlated public type.
+ *
+ * `createSchema` intentionally exposes its generic inferred shape; this
+ * domain wrapper is the typed boundary consumers should use.
+ */
+declare const validateFeedbackGameDiagnostics: (input: unknown) => FeedbackGameDiagnosticsValidationResult;
+
+export { type DeepReadonly as D, FieldBuilder as F, type Infer as I, type PIIEnforcement as P, type RefEntityId as R, type SchemaShape as S, type UnknownFieldsPolicy as U, type ValidationIssue as V, type SchemaOptions as a, type Schema as b, type FieldType as c, FeedbackGameDiagnosticsSchema as d, type FeedbackGameDiagnosticsValidationResult as e, type FieldDefinition as f, type FieldExposure as g, type FieldTypeMap as h, type FieldValidator as i, type FieldValidatorResult as j, SCHEMA_IDENTITY_POLICIES as k, SCHEMA_UNKNOWN_FIELDS_POLICIES as l, type SchemaIdentityPolicy as m, type SchemaUpgradeFunction as n, type SchemaUpgradeResult as o, type SchemaUpgradeSpec as p, type SchemaUpgradeStep as q, type SchemaValidationContext as r, type SerializeOptions as s, type ValidateCompositionOptions as t, type ValidationIssueInput as u, type ValidationResult as v, validateFeedbackGameDiagnostics as w };