Versioning & migration

Pin SDK and Vue package versions together for a trial, record the deployed build, and validate upgrades in a staging assessment before widening rollout. Public package versions and the runtime build SHA are the evidence needed to reproduce browser-specific issues.

Runtime build identity

Published SDK bundles stamp sdkVersion and buildSha. They appear on the delivery canary and the common sdk.* telemetry envelope; the dashboard timeline shows both. Source/test builds fall back to 0.0.0 and development, so do not use those values as a production release identity.

Capture this information with the candidate browser/OS, policy version, correlation id, candidate origin, and incident timestamp.

Compatibility rules

• Keep @a4anthony/proctorkit-sdk and @a4anthony/proctorkit-vue on versions tested together.
• Treat exported TypeScript types, policy normalization, event unions, endpoint schemas, and webhook payloads as one compatibility surface.
• Rebuild shared types and SDK type declarations before checking dependent Vue/dashboard packages in a source checkout.
• Re-run preflight, startup delivery, full-duration media, clean end, dashboard review, API, and webhook tests after an upgrade.
• Do not infer runtime compatibility from a successful package install.

Package, schema, and content releases

ProctorKit content has three independent versions:

After one upgrade to a runtime-content-enabled Vue package, ordinary published copy changes are loaded automatically and become visible on the next page load or refresh. Content releases are immutable. Production rollback moves the compatible schema pointer to an earlier release; it does not modify history or change the installed package. A mounted assessment remains pinned to one release so its wording cannot change halfway through.

The current Vue package requests content schema v4. The server retains the earlier v1, v2, and v3 production pointers for compatible installed packages; publishing or rolling back v4 does not alter an older line. Bundled fallback manifests are generated from the same central catalog used to seed Content Studio.

Host messages overrides remain application code and continue to require a host deployment when changed. A new component state or schema key still needs a compatible package release.

Policy version 3

Resolved assessment policies store policyVersion: 3. The canonical fields are:

• preflight.enabled instead of verificationMode;
• proctoring.webcam.mode: "none" | "snapshots" | "recording" instead of separate snapshots/record booleans;
• proctoring.webcam.faceAnalysis instead of proctoring.face;
• proctoring.screenShare.enabled instead of a separate record mode.

Legacy inputs are accepted at the authoring boundary and normalized away before the policy is emitted/stored. Explicit legacy record: true wins over snapshots during migration. Do not depend on deprecated fields appearing in the resolved policy.

// v2 input (accepted temporarily)
const legacy = {
  verificationMode: "preflight_required",
  proctoring: {
    webcam: { snapshots: true, record: false },
    face: { enabled: true, lostFace: true, multipleFaces: true, gaze: true },
  },
};

// v3 authoring
const current = {
  policyVersion: 3
  preflight  enabled  
  proctoring 
    webcam 
      mode 
      faceAnalysis 
        lostFace 
        multipleFaces 
        gaze 
        identityMismatch 
      
    
  

See Policy migration for precedence and derived rules.

Event and API evolution

Consume event kinds as a typed union but tolerate additional payload fields. Store webhook Idempotency-Key values and verify signatures against the raw body. For REST, branch on HTTP status and the documented response envelope; do not parse human error messages as stable codes unless the endpoint explicitly provides a code.

When adding or removing public fields in your integration, deploy readers before writers where possible and keep a rollback version available. A policy snapshot stored on each session preserves what was intended even if defaults change later.

Upgrade checklist

• Read the release/changelog entry and compare exported types.
• Diff resolved basic, standard, and strict policies.
• Verify legacy policy fixtures still normalize as expected.
• Compile every copied integration example.
• Run desktop browser and slow-network smoke tests.
• Confirm SDK version/build SHA in the dashboard timeline.
• Verify new event kinds render and materialize correctly.
• Verify API/webhook consumers tolerate the new response/payload.
• Update candidate/support documentation and record the rollout/rollback plan.