@plasius/schema 1.2.18 → 1.3.1

package/dist/feedback-diagnostics-CnsI0B9-.d.ts

@@ -0,0 +1,353 @@
+import { FeedbackGameDiagnostics } from './feedback-diagnostics-vocabulary.js';
+
+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 };

package/dist/feedback-diagnostics-vocabulary.cjs

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/feedback-diagnostics-vocabulary.ts
+var feedback_diagnostics_vocabulary_exports = {};
+__export(feedback_diagnostics_vocabulary_exports, {
+  FEEDBACK_BACKEND_BUCKETS: () => FEEDBACK_BACKEND_BUCKETS,
+  FEEDBACK_CONTRACT_VERSION: () => FEEDBACK_CONTRACT_VERSION,
+  FEEDBACK_FRAME_RATE_BUCKETS: () => FEEDBACK_FRAME_RATE_BUCKETS,
+  FEEDBACK_FRAME_TIME_BUCKETS: () => FEEDBACK_FRAME_TIME_BUCKETS,
+  FEEDBACK_GAME_COUNTER_CODES: () => FEEDBACK_GAME_COUNTER_CODES,
+  FEEDBACK_GAME_COUNTER_MAX_COUNT: () => FEEDBACK_GAME_COUNTER_MAX_COUNT,
+  FEEDBACK_GAME_COUNTER_MAX_ITEMS: () => FEEDBACK_GAME_COUNTER_MAX_ITEMS,
+  FEEDBACK_GAME_ERROR_CODES: () => FEEDBACK_GAME_ERROR_CODES,
+  FEEDBACK_GAME_FEATURE_IDS: () => FEEDBACK_GAME_FEATURE_IDS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACTS: () => FEEDBACK_GAME_PROVENANCE_CONTRACTS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS: () => FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS,
+  FEEDBACK_GAME_SURFACE_IDS: () => FEEDBACK_GAME_SURFACE_IDS,
+  FEEDBACK_RENDERER_BUCKETS: () => FEEDBACK_RENDERER_BUCKETS,
+  FEEDBACK_VIEWPORT_BUCKETS: () => FEEDBACK_VIEWPORT_BUCKETS
+});
+module.exports = __toCommonJS(feedback_diagnostics_vocabulary_exports);
+
+// src/feedback-contract-version.ts
+var FEEDBACK_CONTRACT_VERSION = "1.0.0";
+
+// src/feedback-diagnostics-vocabulary.ts
+var FEEDBACK_RENDERER_BUCKETS = [
+  "webgl2",
+  "webgpu",
+  "canvas2d",
+  "unknown"
+];
+var FEEDBACK_BACKEND_BUCKETS = [
+  "browser",
+  "worker",
+  "unknown"
+];
+var FEEDBACK_GAME_SURFACE_IDS = [
+  "site.generator",
+  "site.gpu-demo"
+];
+var FEEDBACK_GAME_PROVENANCE_CONTRACTS = [
+  {
+    surfaceId: "site.generator",
+    contractId: "generator.renderer-diagnostics.v1"
+  },
+  {
+    surfaceId: "site.gpu-demo",
+    contractId: "gpu-demo.renderer-diagnostics.v1"
+  }
+];
+var FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS = [
+  "generator.renderer-diagnostics.v1",
+  "gpu-demo.renderer-diagnostics.v1"
+];
+var FEEDBACK_GAME_FEATURE_IDS = [
+  "renderer.initialisation",
+  "renderer.frame-loop",
+  "renderer.asset-loading",
+  "renderer.input",
+  "renderer.scene-generation",
+  "renderer.post-processing"
+];
+var FEEDBACK_GAME_COUNTER_CODES = [
+  "frame-drop",
+  "device-loss",
+  "asset-load-failure",
+  "shader-failure",
+  "fallback-activation"
+];
+var FEEDBACK_GAME_COUNTER_MAX_ITEMS = 32;
+var FEEDBACK_GAME_COUNTER_MAX_COUNT = 1e4;
+var FEEDBACK_GAME_ERROR_CODES = [
+  "renderer.initialisation-failed",
+  "renderer.device-lost",
+  "renderer.asset-load-failed",
+  "renderer.frame-budget-exceeded",
+  "renderer.shader-failed",
+  "renderer.unknown"
+];
+var FEEDBACK_VIEWPORT_BUCKETS = [
+  "small-portrait",
+  "small-landscape",
+  "medium-portrait",
+  "medium-landscape",
+  "large-portrait",
+  "large-landscape",
+  "unknown"
+];
+var FEEDBACK_FRAME_RATE_BUCKETS = [
+  "under-15",
+  "15-29",
+  "30-59",
+  "60-plus",
+  "unknown"
+];
+var FEEDBACK_FRAME_TIME_BUCKETS = [
+  "under-17ms",
+  "17-33ms",
+  "34-66ms",
+  "over-66ms",
+  "unknown"
+];
+for (const vocabulary of [
+  FEEDBACK_RENDERER_BUCKETS,
+  FEEDBACK_BACKEND_BUCKETS,
+  FEEDBACK_GAME_SURFACE_IDS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACTS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS,
+  FEEDBACK_GAME_FEATURE_IDS,
+  FEEDBACK_GAME_COUNTER_CODES,
+  FEEDBACK_GAME_ERROR_CODES,
+  FEEDBACK_VIEWPORT_BUCKETS,
+  FEEDBACK_FRAME_RATE_BUCKETS,
+  FEEDBACK_FRAME_TIME_BUCKETS
+]) {
+  Object.freeze(vocabulary);
+}
+for (const entry of FEEDBACK_GAME_PROVENANCE_CONTRACTS) {
+  Object.freeze(entry);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FEEDBACK_BACKEND_BUCKETS,
+  FEEDBACK_CONTRACT_VERSION,
+  FEEDBACK_FRAME_RATE_BUCKETS,
+  FEEDBACK_FRAME_TIME_BUCKETS,
+  FEEDBACK_GAME_COUNTER_CODES,
+  FEEDBACK_GAME_COUNTER_MAX_COUNT,
+  FEEDBACK_GAME_COUNTER_MAX_ITEMS,
+  FEEDBACK_GAME_ERROR_CODES,
+  FEEDBACK_GAME_FEATURE_IDS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACTS,
+  FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS,
+  FEEDBACK_GAME_SURFACE_IDS,
+  FEEDBACK_RENDERER_BUCKETS,
+  FEEDBACK_VIEWPORT_BUCKETS
+});
+//# sourceMappingURL=feedback-diagnostics-vocabulary.cjs.map

package/dist/feedback-diagnostics-vocabulary.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/feedback-diagnostics-vocabulary.ts","../src/feedback-contract-version.ts"],"sourcesContent":["import { FEEDBACK_CONTRACT_VERSION } from \"./feedback-contract-version.js\";\n\nexport { FEEDBACK_CONTRACT_VERSION };\n\n/** Coarse renderer buckets permitted in privacy-safe game diagnostics. */\nexport const FEEDBACK_RENDERER_BUCKETS = [\n  \"webgl2\",\n  \"webgpu\",\n  \"canvas2d\",\n  \"unknown\",\n] as const;\n\n/** Coarse execution-backend buckets permitted in game diagnostics. */\nexport const FEEDBACK_BACKEND_BUCKETS = [\n  \"browser\",\n  \"worker\",\n  \"unknown\",\n] as const;\n\n/** Renderer surfaces approved to carry diagnostics in the first contract. */\nexport const FEEDBACK_GAME_SURFACE_IDS = [\n  \"site.generator\",\n  \"site.gpu-demo\",\n] as const;\n\n/** Exact renderer-owned provenance contracts for approved game surfaces. */\nexport const FEEDBACK_GAME_PROVENANCE_CONTRACTS = [\n  {\n    surfaceId: \"site.generator\",\n    contractId: \"generator.renderer-diagnostics.v1\",\n  },\n  {\n    surfaceId: \"site.gpu-demo\",\n    contractId: \"gpu-demo.renderer-diagnostics.v1\",\n  },\n] as const;\n\n/** Closed provenance identifiers accepted from the browser. */\nexport const FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS = [\n  \"generator.renderer-diagnostics.v1\",\n  \"gpu-demo.renderer-diagnostics.v1\",\n] as const;\n\n/** Closed renderer feature identifiers accepted from the browser. */\nexport const FEEDBACK_GAME_FEATURE_IDS = [\n  \"renderer.initialisation\",\n  \"renderer.frame-loop\",\n  \"renderer.asset-loading\",\n  \"renderer.input\",\n  \"renderer.scene-generation\",\n  \"renderer.post-processing\",\n] as const;\n\n/** Closed renderer counter identifiers accepted from the browser. */\nexport const FEEDBACK_GAME_COUNTER_CODES = [\n  \"frame-drop\",\n  \"device-loss\",\n  \"asset-load-failure\",\n  \"shader-failure\",\n  \"fallback-activation\",\n] as const;\n\n/** Maximum number of distinct coarse counters in one diagnostics packet. */\nexport const FEEDBACK_GAME_COUNTER_MAX_ITEMS = 32;\n\n/** Maximum value accepted for one coarse diagnostics counter. */\nexport const FEEDBACK_GAME_COUNTER_MAX_COUNT = 10_000;\n\n/** Closed renderer error identifiers accepted from the browser. */\nexport const FEEDBACK_GAME_ERROR_CODES = [\n  \"renderer.initialisation-failed\",\n  \"renderer.device-lost\",\n  \"renderer.asset-load-failed\",\n  \"renderer.frame-budget-exceeded\",\n  \"renderer.shader-failed\",\n  \"renderer.unknown\",\n] as const;\n\n/** Coarse viewport buckets; exact dimensions are deliberately excluded. */\nexport const FEEDBACK_VIEWPORT_BUCKETS = [\n  \"small-portrait\",\n  \"small-landscape\",\n  \"medium-portrait\",\n  \"medium-landscape\",\n  \"large-portrait\",\n  \"large-landscape\",\n  \"unknown\",\n] as const;\n\n/** Coarse frame-rate buckets permitted in game diagnostics. */\nexport const FEEDBACK_FRAME_RATE_BUCKETS = [\n  \"under-15\",\n  \"15-29\",\n  \"30-59\",\n  \"60-plus\",\n  \"unknown\",\n] as const;\n\n/** Coarse frame-time buckets permitted in game diagnostics. */\nexport const FEEDBACK_FRAME_TIME_BUCKETS = [\n  \"under-17ms\",\n  \"17-33ms\",\n  \"34-66ms\",\n  \"over-66ms\",\n  \"unknown\",\n] as const;\n\nfor (const vocabulary of [\n  FEEDBACK_RENDERER_BUCKETS,\n  FEEDBACK_BACKEND_BUCKETS,\n  FEEDBACK_GAME_SURFACE_IDS,\n  FEEDBACK_GAME_PROVENANCE_CONTRACTS,\n  FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS,\n  FEEDBACK_GAME_FEATURE_IDS,\n  FEEDBACK_GAME_COUNTER_CODES,\n  FEEDBACK_GAME_ERROR_CODES,\n  FEEDBACK_VIEWPORT_BUCKETS,\n  FEEDBACK_FRAME_RATE_BUCKETS,\n  FEEDBACK_FRAME_TIME_BUCKETS,\n]) {\n  Object.freeze(vocabulary);\n}\nfor (const entry of FEEDBACK_GAME_PROVENANCE_CONTRACTS) {\n  Object.freeze(entry);\n}\n\n/** Fields shared by every coarse, consented game-diagnostics packet. */\ninterface FeedbackGameDiagnosticsBase {\n  type: \"feedback-game-diagnostics\";\n  version: typeof FEEDBACK_CONTRACT_VERSION;\n  consentConfirmed: true;\n  renderer: (typeof FEEDBACK_RENDERER_BUCKETS)[number];\n  backend: (typeof FEEDBACK_BACKEND_BUCKETS)[number];\n  viewportBucket: (typeof FEEDBACK_VIEWPORT_BUCKETS)[number];\n  frameRateBucket: (typeof FEEDBACK_FRAME_RATE_BUCKETS)[number];\n  frameTimeBucket: (typeof FEEDBACK_FRAME_TIME_BUCKETS)[number];\n  featureIds: readonly (typeof FEEDBACK_GAME_FEATURE_IDS)[number][];\n  counters: readonly {\n    code: (typeof FEEDBACK_GAME_COUNTER_CODES)[number];\n    count: number;\n  }[];\n  errorCodes: readonly (typeof FEEDBACK_GAME_ERROR_CODES)[number][];\n}\n\ntype FeedbackGameProvenanceContract =\n  (typeof FEEDBACK_GAME_PROVENANCE_CONTRACTS)[number];\n\ntype FeedbackGameProvenancePair = {\n  [SurfaceId in FeedbackGameProvenanceContract[\"surfaceId\"]]: {\n    surfaceId: SurfaceId;\n    provenanceContractId: Extract<\n      FeedbackGameProvenanceContract,\n      { surfaceId: SurfaceId }\n    >[\"contractId\"];\n  };\n}[FeedbackGameProvenanceContract[\"surfaceId\"]];\n\n/**\n * Coarse, consented game facts that cannot express captured pixels.\n *\n * The discriminated union prevents a renderer from pairing one approved\n * surface with another surface's provenance contract at compile time.\n */\nexport type FeedbackGameDiagnostics = FeedbackGameDiagnosticsBase &\n  FeedbackGameProvenancePair;\n","/** Version shared by the first privacy-safe feedback contracts. */\nexport const FEEDBACK_CONTRACT_VERSION = \"1.0.0\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCO,IAAM,4BAA4B;;;ADIlC,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AACF;AAGO,IAAM,qCAAqC;AAAA,EAChD;AAAA,IACE,WAAW;AAAA,IACX,YAAY;AAAA,EACd;AAAA,EACA;AAAA,IACE,WAAW;AAAA,IACX,YAAY;AAAA,EACd;AACF;AAGO,IAAM,wCAAwC;AAAA,EACnD;AAAA,EACA;AACF;AAGO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,kCAAkC;AAGxC,IAAM,kCAAkC;AAGxC,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,WAAW,cAAc;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAG;AACD,SAAO,OAAO,UAAU;AAC1B;AACA,WAAW,SAAS,oCAAoC;AACtD,SAAO,OAAO,KAAK;AACrB;","names":[]}

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

@@ -0,0 +1,70 @@
+/** Version shared by the first privacy-safe feedback contracts. */
+declare const FEEDBACK_CONTRACT_VERSION = "1.0.0";
+
+/** Coarse renderer buckets permitted in privacy-safe game diagnostics. */
+declare const FEEDBACK_RENDERER_BUCKETS: readonly ["webgl2", "webgpu", "canvas2d", "unknown"];
+/** Coarse execution-backend buckets permitted in game diagnostics. */
+declare const FEEDBACK_BACKEND_BUCKETS: readonly ["browser", "worker", "unknown"];
+/** Renderer surfaces approved to carry diagnostics in the first contract. */
+declare const FEEDBACK_GAME_SURFACE_IDS: readonly ["site.generator", "site.gpu-demo"];
+/** Exact renderer-owned provenance contracts for approved game surfaces. */
+declare const FEEDBACK_GAME_PROVENANCE_CONTRACTS: readonly [{
+    readonly surfaceId: "site.generator";
+    readonly contractId: "generator.renderer-diagnostics.v1";
+}, {
+    readonly surfaceId: "site.gpu-demo";
+    readonly contractId: "gpu-demo.renderer-diagnostics.v1";
+}];
+/** Closed provenance identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS: readonly ["generator.renderer-diagnostics.v1", "gpu-demo.renderer-diagnostics.v1"];
+/** Closed renderer feature identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_FEATURE_IDS: readonly ["renderer.initialisation", "renderer.frame-loop", "renderer.asset-loading", "renderer.input", "renderer.scene-generation", "renderer.post-processing"];
+/** Closed renderer counter identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_COUNTER_CODES: readonly ["frame-drop", "device-loss", "asset-load-failure", "shader-failure", "fallback-activation"];
+/** Maximum number of distinct coarse counters in one diagnostics packet. */
+declare const FEEDBACK_GAME_COUNTER_MAX_ITEMS = 32;
+/** Maximum value accepted for one coarse diagnostics counter. */
+declare const FEEDBACK_GAME_COUNTER_MAX_COUNT = 10000;
+/** Closed renderer error identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_ERROR_CODES: readonly ["renderer.initialisation-failed", "renderer.device-lost", "renderer.asset-load-failed", "renderer.frame-budget-exceeded", "renderer.shader-failed", "renderer.unknown"];
+/** Coarse viewport buckets; exact dimensions are deliberately excluded. */
+declare const FEEDBACK_VIEWPORT_BUCKETS: readonly ["small-portrait", "small-landscape", "medium-portrait", "medium-landscape", "large-portrait", "large-landscape", "unknown"];
+/** Coarse frame-rate buckets permitted in game diagnostics. */
+declare const FEEDBACK_FRAME_RATE_BUCKETS: readonly ["under-15", "15-29", "30-59", "60-plus", "unknown"];
+/** Coarse frame-time buckets permitted in game diagnostics. */
+declare const FEEDBACK_FRAME_TIME_BUCKETS: readonly ["under-17ms", "17-33ms", "34-66ms", "over-66ms", "unknown"];
+/** Fields shared by every coarse, consented game-diagnostics packet. */
+interface FeedbackGameDiagnosticsBase {
+    type: "feedback-game-diagnostics";
+    version: typeof FEEDBACK_CONTRACT_VERSION;
+    consentConfirmed: true;
+    renderer: (typeof FEEDBACK_RENDERER_BUCKETS)[number];
+    backend: (typeof FEEDBACK_BACKEND_BUCKETS)[number];
+    viewportBucket: (typeof FEEDBACK_VIEWPORT_BUCKETS)[number];
+    frameRateBucket: (typeof FEEDBACK_FRAME_RATE_BUCKETS)[number];
+    frameTimeBucket: (typeof FEEDBACK_FRAME_TIME_BUCKETS)[number];
+    featureIds: readonly (typeof FEEDBACK_GAME_FEATURE_IDS)[number][];
+    counters: readonly {
+        code: (typeof FEEDBACK_GAME_COUNTER_CODES)[number];
+        count: number;
+    }[];
+    errorCodes: readonly (typeof FEEDBACK_GAME_ERROR_CODES)[number][];
+}
+type FeedbackGameProvenanceContract = (typeof FEEDBACK_GAME_PROVENANCE_CONTRACTS)[number];
+type FeedbackGameProvenancePair = {
+    [SurfaceId in FeedbackGameProvenanceContract["surfaceId"]]: {
+        surfaceId: SurfaceId;
+        provenanceContractId: Extract<FeedbackGameProvenanceContract, {
+            surfaceId: SurfaceId;
+        }>["contractId"];
+    };
+}[FeedbackGameProvenanceContract["surfaceId"]];
+/**
+ * Coarse, consented game facts that cannot express captured pixels.
+ *
+ * The discriminated union prevents a renderer from pairing one approved
+ * surface with another surface's provenance contract at compile time.
+ */
+type FeedbackGameDiagnostics = FeedbackGameDiagnosticsBase & FeedbackGameProvenancePair;
+
+export { FEEDBACK_BACKEND_BUCKETS, FEEDBACK_CONTRACT_VERSION, FEEDBACK_FRAME_RATE_BUCKETS, FEEDBACK_FRAME_TIME_BUCKETS, FEEDBACK_GAME_COUNTER_CODES, FEEDBACK_GAME_COUNTER_MAX_COUNT, FEEDBACK_GAME_COUNTER_MAX_ITEMS, FEEDBACK_GAME_ERROR_CODES, FEEDBACK_GAME_FEATURE_IDS, FEEDBACK_GAME_PROVENANCE_CONTRACTS, FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS, FEEDBACK_GAME_SURFACE_IDS, FEEDBACK_RENDERER_BUCKETS, FEEDBACK_VIEWPORT_BUCKETS, type FeedbackGameDiagnostics };

package/dist/feedback-diagnostics-vocabulary.d.ts

@@ -0,0 +1,70 @@
+/** Version shared by the first privacy-safe feedback contracts. */
+declare const FEEDBACK_CONTRACT_VERSION = "1.0.0";
+
+/** Coarse renderer buckets permitted in privacy-safe game diagnostics. */
+declare const FEEDBACK_RENDERER_BUCKETS: readonly ["webgl2", "webgpu", "canvas2d", "unknown"];
+/** Coarse execution-backend buckets permitted in game diagnostics. */
+declare const FEEDBACK_BACKEND_BUCKETS: readonly ["browser", "worker", "unknown"];
+/** Renderer surfaces approved to carry diagnostics in the first contract. */
+declare const FEEDBACK_GAME_SURFACE_IDS: readonly ["site.generator", "site.gpu-demo"];
+/** Exact renderer-owned provenance contracts for approved game surfaces. */
+declare const FEEDBACK_GAME_PROVENANCE_CONTRACTS: readonly [{
+    readonly surfaceId: "site.generator";
+    readonly contractId: "generator.renderer-diagnostics.v1";
+}, {
+    readonly surfaceId: "site.gpu-demo";
+    readonly contractId: "gpu-demo.renderer-diagnostics.v1";
+}];
+/** Closed provenance identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS: readonly ["generator.renderer-diagnostics.v1", "gpu-demo.renderer-diagnostics.v1"];
+/** Closed renderer feature identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_FEATURE_IDS: readonly ["renderer.initialisation", "renderer.frame-loop", "renderer.asset-loading", "renderer.input", "renderer.scene-generation", "renderer.post-processing"];
+/** Closed renderer counter identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_COUNTER_CODES: readonly ["frame-drop", "device-loss", "asset-load-failure", "shader-failure", "fallback-activation"];
+/** Maximum number of distinct coarse counters in one diagnostics packet. */
+declare const FEEDBACK_GAME_COUNTER_MAX_ITEMS = 32;
+/** Maximum value accepted for one coarse diagnostics counter. */
+declare const FEEDBACK_GAME_COUNTER_MAX_COUNT = 10000;
+/** Closed renderer error identifiers accepted from the browser. */
+declare const FEEDBACK_GAME_ERROR_CODES: readonly ["renderer.initialisation-failed", "renderer.device-lost", "renderer.asset-load-failed", "renderer.frame-budget-exceeded", "renderer.shader-failed", "renderer.unknown"];
+/** Coarse viewport buckets; exact dimensions are deliberately excluded. */
+declare const FEEDBACK_VIEWPORT_BUCKETS: readonly ["small-portrait", "small-landscape", "medium-portrait", "medium-landscape", "large-portrait", "large-landscape", "unknown"];
+/** Coarse frame-rate buckets permitted in game diagnostics. */
+declare const FEEDBACK_FRAME_RATE_BUCKETS: readonly ["under-15", "15-29", "30-59", "60-plus", "unknown"];
+/** Coarse frame-time buckets permitted in game diagnostics. */
+declare const FEEDBACK_FRAME_TIME_BUCKETS: readonly ["under-17ms", "17-33ms", "34-66ms", "over-66ms", "unknown"];
+/** Fields shared by every coarse, consented game-diagnostics packet. */
+interface FeedbackGameDiagnosticsBase {
+    type: "feedback-game-diagnostics";
+    version: typeof FEEDBACK_CONTRACT_VERSION;
+    consentConfirmed: true;
+    renderer: (typeof FEEDBACK_RENDERER_BUCKETS)[number];
+    backend: (typeof FEEDBACK_BACKEND_BUCKETS)[number];
+    viewportBucket: (typeof FEEDBACK_VIEWPORT_BUCKETS)[number];
+    frameRateBucket: (typeof FEEDBACK_FRAME_RATE_BUCKETS)[number];
+    frameTimeBucket: (typeof FEEDBACK_FRAME_TIME_BUCKETS)[number];
+    featureIds: readonly (typeof FEEDBACK_GAME_FEATURE_IDS)[number][];
+    counters: readonly {
+        code: (typeof FEEDBACK_GAME_COUNTER_CODES)[number];
+        count: number;
+    }[];
+    errorCodes: readonly (typeof FEEDBACK_GAME_ERROR_CODES)[number][];
+}
+type FeedbackGameProvenanceContract = (typeof FEEDBACK_GAME_PROVENANCE_CONTRACTS)[number];
+type FeedbackGameProvenancePair = {
+    [SurfaceId in FeedbackGameProvenanceContract["surfaceId"]]: {
+        surfaceId: SurfaceId;
+        provenanceContractId: Extract<FeedbackGameProvenanceContract, {
+            surfaceId: SurfaceId;
+        }>["contractId"];
+    };
+}[FeedbackGameProvenanceContract["surfaceId"]];
+/**
+ * Coarse, consented game facts that cannot express captured pixels.
+ *
+ * The discriminated union prevents a renderer from pairing one approved
+ * surface with another surface's provenance contract at compile time.
+ */
+type FeedbackGameDiagnostics = FeedbackGameDiagnosticsBase & FeedbackGameProvenancePair;
+
+export { FEEDBACK_BACKEND_BUCKETS, FEEDBACK_CONTRACT_VERSION, FEEDBACK_FRAME_RATE_BUCKETS, FEEDBACK_FRAME_TIME_BUCKETS, FEEDBACK_GAME_COUNTER_CODES, FEEDBACK_GAME_COUNTER_MAX_COUNT, FEEDBACK_GAME_COUNTER_MAX_ITEMS, FEEDBACK_GAME_ERROR_CODES, FEEDBACK_GAME_FEATURE_IDS, FEEDBACK_GAME_PROVENANCE_CONTRACTS, FEEDBACK_GAME_PROVENANCE_CONTRACT_IDS, FEEDBACK_GAME_SURFACE_IDS, FEEDBACK_RENDERER_BUCKETS, FEEDBACK_VIEWPORT_BUCKETS, type FeedbackGameDiagnostics };