@dyno-cloud/schema 0.0.0-stage → 0.1.3

package/json/run-request.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "RunRequest",
+  "description": "What dyno asks a driver to run.",
+  "type": "object",
+  "properties": {
+    "host_profile": {
+      "$ref": "#/$defs/HostProfile"
+    },
+    "idle_after_ms": {
+      "description": "The game frame is idle after this long with no new requests.",
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0
+    },
+    "launch_url": {
+      "description": "The full launch URL, query string included. It never goes into a result.",
+      "type": "string"
+    },
+    "protocol_version": {
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0
+    },
+    "scenario": {
+      "$ref": "#/$defs/Scenario"
+    },
+    "spins": {
+      "description": "Demo spins to play after load (Phase 2). Null for a load-and-idle run.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0
+    },
+    "timeout_ms": {
+      "description": "The driver stops and sends an error after this long.",
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "protocol_version",
+    "launch_url",
+    "host_profile",
+    "scenario",
+    "idle_after_ms",
+    "timeout_ms"
+  ],
+  "$defs": {
+    "HostProfile": {
+      "description": "How a host page embeds a game, and the device facts the static formulas use. Reels is the\nfirst host profile. It holds no assumed cost: the device run measures those.",
+      "type": "object",
+      "properties": {
+        "active_message": {
+          "description": "The message the host sends when the game becomes active, such as `reels:active`.",
+          "type": "string"
+        },
+        "device_scale_factor": {
+          "description": "The device pixel ratio the run forces. The reference iPhone's is 3.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "name": {
+          "type": "string"
+        },
+        "pcm_low_rate_hz": {
+          "description": "The lower context rate that fixes suggest. The measure ids name 24 kHz, so a change needs\nnew ids.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "pcm_rate_hz": {
+          "description": "The audio context's sample rate on the reference iPhone. Decoded audio is held at this\nrate. The measure ids name 48 kHz, so a change needs new ids.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "ready_message": {
+          "description": "The message the game sends when it is ready, such as `reels:ready`.",
+          "type": "string"
+        },
+        "ready_within_ms": {
+          "description": "The contract's limit on time to the ready message.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "version": {
+          "description": "Bumps when any value below changes.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "viewport": {
+          "description": "The game frame's size in CSS pixels.",
+          "$ref": "#/$defs/Viewport"
+        },
+        "webgpu": {
+          "description": "Whether the reference browser has WebGPU on. When it is off, a game that asks for WebGPU\ngets WebGL.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "name",
+        "version",
+        "ready_message",
+        "active_message",
+        "ready_within_ms",
+        "viewport",
+        "device_scale_factor",
+        "webgpu",
+        "pcm_rate_hz",
+        "pcm_low_rate_hz"
+      ]
+    },
+    "Scenario": {
+      "description": "The harness scenario of a browser run.",
+      "oneOf": [
+        {
+          "description": "The game alone in a fresh harness page (Phase 1).",
+          "type": "string",
+          "const": "alone"
+        },
+        {
+          "description": "The harness page after 10 earlier games (Phase 2).",
+          "type": "string",
+          "const": "aged"
+        },
+        {
+          "description": "One game active while the next one preloads (Phase 2).",
+          "type": "string",
+          "const": "overlap"
+        }
+      ]
+    },
+    "Viewport": {
+      "description": "A size in CSS pixels.",
+      "type": "object",
+      "properties": {
+        "height": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "width": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ]
+    }
+  }
+}

package/json/unclean-exit.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "UncleanExit",
+  "description": "An observed unclean exit: the last page died with game frames live. Never sampled.",
+  "type": "object",
+  "properties": {
+    "frames": {
+      "description": "The game frames that were live when the page died.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/LiveFrame"
+      }
+    },
+    "host_profile": {
+      "description": "The host profile, such as reels version 0.",
+      "$ref": "#/$defs/ProfileRef"
+    },
+    "schema_version": {
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "schema_version",
+    "host_profile",
+    "frames"
+  ],
+  "$defs": {
+    "FrameState": {
+      "description": "Whether a game frame is the one on screen. Reels calls an inactive frame preloaded.",
+      "oneOf": [
+        {
+          "description": "On screen, after the host's active message.",
+          "type": "string",
+          "const": "active"
+        },
+        {
+          "description": "Mounted but not on screen.",
+          "type": "string",
+          "const": "inactive"
+        }
+      ]
+    },
+    "LiveFrame": {
+      "description": "A game frame that was live when the page died.",
+      "type": "object",
+      "properties": {
+        "build_version": {
+          "description": "From the frame URL, such as \"v12\" from `/v12/`. Null when the URL has none.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "frame_state": {
+          "$ref": "#/$defs/FrameState"
+        },
+        "game_id": {
+          "type": "string"
+        },
+        "mount_age_ms": {
+          "description": "Time since the frame was mounted.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "ready_seen": {
+          "description": "Whether the host saw the game's ready message.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "game_id",
+        "frame_state",
+        "mount_age_ms",
+        "ready_seen"
+      ]
+    },
+    "ProfileRef": {
+      "description": "Which host profile, and which version of it, a result used.",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "name",
+        "version"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@dyno-cloud/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "TypeScript types and JSON Schema for the JSON that dyno writes: check results, compare results, the runner protocol and the probe events.",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dyno-labs/dyno.git",
+    "directory": "packages/schema"
+  },
+  "files": [
+    "json/*.json",
+    "ts/*.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./ts/index.ts",
+  "exports": {
+    ".": {
+      "types": "./ts/index.ts"
+    },
+    "./json/*": "./json/*"
+  }
+}

package/ts/AssetChange.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AssetChangeKind } from "./AssetChangeKind";
+import type { RelPath } from "./RelPath";
+
+/**
+ * One file that differs between the two build manifests.
+ */
+export type AssetChange = { path: RelPath, change: AssetChangeKind, base_bytes: number | null, head_bytes: number | null, };

package/ts/AssetChangeKind.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How a file changed.
+ */
+export type AssetChangeKind = "added" | "removed" | "changed";

package/ts/AssignedRole.ts

@@ -0,0 +1,7 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ProcessRole } from "./ProcessRole";
+
+/**
+ * One process's part in a `roles` message.
+ */
+export type AssignedRole = { pid: number, role: ProcessRole, };

package/ts/AudioState.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * An audio context's state.
+ */
+export type AudioState = "running" | "suspended" | "closed";

package/ts/BrowserEngine.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A browser engine.
+ */
+export type BrowserEngine = "blink" | "webkit" | "gecko";

package/ts/BudgetId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Every budget a budget file can set. Each id is the key path in the file.
+ */
+export type BudgetId = "audio.decoded_mb" | "audio.stereo_saving_mb" | "audio.silence_share_bp" | "audio.silence_saving_mb" | "textures.decoded_mb" | "render.antialias" | "render.resolution_uncapped" | "files.duplicate";

package/ts/BudgetLimit.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Severity } from "./Severity";
+
+/**
+ * A budget's limit as a verdict or rule reads it: sizes in bytes, shares in basis points, and
+ * flags as a severity.
+ */
+export type BudgetLimit = { "kind": "bytes", warn_above: number | null, fail_above: number | null, } | { "kind": "flag", when_on: Severity, } | { "kind": "basis_points", warn_above: number | null, fail_above: number | null, };

package/ts/BudgetRef.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Which budget file a result used.
+ */
+export type BudgetRef = { 
+/**
+ * The file's `name`, if it has one.
+ */
+name: string | null, 
+/**
+ * Lowercase hex SHA-256 of the parsed budgets as canonical JSON. The same budgets in TOML
+ * and JSON give the same hash, and comments do not change it.
+ */
+sha256: string, };

package/ts/BudgetVerdict.ts

@@ -0,0 +1,22 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BudgetId } from "./BudgetId";
+import type { BudgetLimit } from "./BudgetLimit";
+import type { MeasureId } from "./MeasureId";
+import type { MeasureValue } from "./MeasureValue";
+import type { Verdict } from "./Verdict";
+
+/**
+ * The verdict of one budget. Only budgets that `dyno-score` checks get one, never a rule's
+ * threshold.
+ */
+export type BudgetVerdict = { budget: BudgetId, measure: MeasureId, 
+/**
+ * A partial value, one whose scope has a `not_covered` entry, is a floor. It gives a verdict
+ * only when the full value could not give a worse one. Otherwise the verdict is incomplete.
+ */
+verdict: Verdict, 
+/**
+ * The measure's value. Null when it has no usable value: none, a status other than measured
+ * or estimated, or a bad number.
+ */
+actual: MeasureValue | null, limit: BudgetLimit, };

package/ts/BuildLink.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How a run's evidence ties to the build it names.
+ */
+export type BuildLink = "none" | "scanned" | "served" | "asserted";

package/ts/BuildManifest.ts

@@ -0,0 +1,17 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ManifestFile } from "./ManifestFile";
+
+/**
+ * Every supplied file of one build. `compare` diffs two manifests to find suspect assets.
+ */
+export type BuildManifest = { 
+/**
+ * Lowercase hex SHA-256 over every file's path and SHA-256, sorted by path, so a rename
+ * changes it. It is the join key for lab and field rows, and does not cover external URLs.
+ * Null until the inventory is implemented. docs/design/static-scan.md gives the exact bytes.
+ */
+build_id: string | null, 
+/**
+ * Sorted by path.
+ */
+files: Array<ManifestFile>, };

package/ts/CatalogueEntry.ts

@@ -0,0 +1,7 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { CheckResult } from "./CheckResult";
+
+/**
+ * One game's result in a catalogue run. Each result keeps its own hash.
+ */
+export type CatalogueEntry = { id: string, result: CheckResult, };

package/ts/CatalogueResult.ts

@@ -0,0 +1,22 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { CatalogueEntry } from "./CatalogueEntry";
+import type { Shard } from "./Shard";
+import type { Status } from "./Status";
+
+/**
+ * The output of a catalogue run.
+ */
+export type CatalogueResult = { schema_version: number, 
+/**
+ * Null when the run covered every game.
+ */
+shard: Shard | null, 
+/**
+ * The worst status of any game, by the precedence on `Status`. Incomplete when the
+ * selection has no games, because an empty run checked nothing.
+ */
+status: Status, 
+/**
+ * Sorted by game id.
+ */
+games: Array<CatalogueEntry>, };

package/ts/CheckResult.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Deterministic } from "./Deterministic";
+import type { RunInfo } from "./RunInfo";
+
+/**
+ * The output of `dyno check` for one target.
+ */
+export type CheckResult = { 
+/**
+ * Read this first. It bumps only on a breaking change.
+ */
+schema_version: number, 
+/**
+ * Lowercase hex SHA-256 of the RFC 8785 canonical JSON of `deterministic`.
+ */
+result_hash: string, deterministic: Deterministic, run: RunInfo, };

package/ts/CompareDeterministic.ts

@@ -0,0 +1,42 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AssetChange } from "./AssetChange";
+import type { BudgetRef } from "./BudgetRef";
+import type { MeasureChange } from "./MeasureChange";
+import type { ResultRef } from "./ResultRef";
+import type { Status } from "./Status";
+import type { VerdictChange } from "./VerdictChange";
+
+/**
+ * Everything the same two results, tool version and budget file give on any machine.
+ */
+export type CompareDeterministic = { 
+/**
+ * The dyno version, such as "0.1.0".
+ */
+tool: string, scoring: number, 
+/**
+ * The budget file applied to both sides. Null to keep each result's own verdicts.
+ */
+budget: BudgetRef | null, base: ResultRef, head: ResultRef, 
+/**
+ * Fail when a budget verdict got worse. Incomplete when either side is incomplete. Invalid
+ * when either side's hash does not match its content.
+ */
+status: Status, 
+/**
+ * Why the status is incomplete or invalid. Null otherwise.
+ */
+reason: string | null, 
+/**
+ * Every deterministic measure that moved. Sorted by id, then by canonical JSON.
+ */
+measures: Array<MeasureChange>, 
+/**
+ * Every budget verdict that changed. Sorted by budget id, then by canonical JSON.
+ */
+verdicts: Array<VerdictChange>, 
+/**
+ * Files that differ between the two build manifests. Sorted by path, then by canonical
+ * JSON.
+ */
+suspect_assets: Array<AssetChange>, };

package/ts/CompareResult.ts

@@ -0,0 +1,12 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { CompareDeterministic } from "./CompareDeterministic";
+import type { CompareRun } from "./CompareRun";
+
+/**
+ * The output of `dyno compare`.
+ */
+export type CompareResult = { schema_version: number, 
+/**
+ * Lowercase hex SHA-256 of the RFC 8785 canonical JSON of `deterministic`.
+ */
+result_hash: string, deterministic: CompareDeterministic, run: CompareRun, };

package/ts/CompareRun.ts

@@ -0,0 +1,17 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Machine } from "./Machine";
+import type { Release } from "./Release";
+import type { ToolBuild } from "./ToolBuild";
+
+/**
+ * What differs between machines and runs. The hash excludes it.
+ */
+export type CompareRun = { 
+/**
+ * RFC 3339 UTC time the compare started.
+ */
+started_at: string, duration_ms: number, machine: Machine, tool_build: ToolBuild, 
+/**
+ * The release labels of each side, from its own run part.
+ */
+base_release: Release, head_release: Release, };

package/ts/ContextKind.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A canvas rendering context's kind.
+ */
+export type ContextKind = "webgl" | "webgl2" | "webgpu" | "canvas2d";

package/ts/Covers.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The set of things a value covers.
+ */
+export type Covers = "supplied_files" | "load_to_idle" | "demo_spins" | "fresh_device_runs" | "model_inputs";

package/ts/Deterministic.ts

@@ -0,0 +1,35 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BudgetVerdict } from "./BudgetVerdict";
+import type { BuildManifest } from "./BuildManifest";
+import type { Finding } from "./Finding";
+import type { Inputs } from "./Inputs";
+import type { Measure } from "./Measure";
+import type { RunCoverage } from "./RunCoverage";
+import type { Status } from "./Status";
+import type { Versions } from "./Versions";
+
+/**
+ * Everything the same build, tool version and budget file give on any machine.
+ */
+export type Deterministic = { versions: Versions, inputs: Inputs, 
+/**
+ * The build's files and id. Null when the check had no build folder, or the inventory has
+ * not listed it yet.
+ */
+build: BuildManifest | null, 
+/**
+ * The overall status. The exit code comes from it alone.
+ */
+status: Status, run_coverage: RunCoverage, 
+/**
+ * Static measures. Sorted by id.
+ */
+measures: Array<Measure>, 
+/**
+ * One verdict per budget the budget file sets. Sorted by budget id.
+ */
+verdicts: Array<BudgetVerdict>, 
+/**
+ * Static rule findings. Sorted by rule id, then by canonical JSON.
+ */
+findings: Array<Finding>, };

package/ts/DeviceClass.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The phone class a tier is for.
+ */
+export type DeviceClass = "reference_iphone";

package/ts/DeviceEntry.ts

@@ -0,0 +1,25 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { DeviceKind } from "./DeviceKind";
+import type { OsName } from "./OsName";
+
+/**
+ * One device in the catalogue.
+ */
+export type DeviceEntry = { 
+/**
+ * The slug of the name, such as "iphone-14-pro-max".
+ */
+key: string, 
+/**
+ * The model name, such as "iPhone 14 Pro Max".
+ */
+name: string, vendor: string, kind: DeviceKind, os_family: OsName, 
+/**
+ * The year the model came out.
+ */
+year: number, 
+/**
+ * Apple's model identifiers for it, such as "iPhone15,3": what the phone gives as its
+ * `ProductType`.
+ */
+identifiers: Array<string>, };

package/ts/DeviceKind.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A kind of device.
+ */
+export type DeviceKind = "phone" | "tablet" | "desktop";

package/ts/DoctorCheck.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { DoctorCheckId } from "./DoctorCheckId";
+import type { Verdict } from "./Verdict";
+
+/**
+ * One doctor check.
+ */
+export type DoctorCheck = { id: DoctorCheckId, verdict: Verdict, phase: number, 
+/**
+ * What the check found, such as the Xcode version. Null when it found nothing.
+ */
+detail: string | null, 
+/**
+ * Why the verdict is incomplete. Null otherwise.
+ */
+reason: string | null, };

package/ts/DoctorCheckId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The things `doctor` checks. Declared in alphabetical order, so checks sort by name.
+ */
+export type DoctorCheckId = "device_connection" | "device_trust" | "xcode";