Schema Diagnostics

The Schema Diagnostics page provides a developer-facing view of your Vextro schema metadata. It shows all registered collections and globals, their field configurations, fingerprint sync status, and helps identify stale or archived metadata that may need attention.

Setup

Import the page component and mount it in your Astro routing:

---
import VextroSchemaDiagnosticsPage from "vextro/pages/VextroSchemaDiagnosticsPage.astro";
---

<VextroSchemaDiagnosticsPage
  convex={convex}
  api={api}
  basePath="/admin"
  config={config}
/>

Page props

Features

Fingerprint status

A banner at the top shows whether the schema metadata is in sync:

The fingerprint details section shows the current fingerprint, stored fingerprint, and last seeded timestamp.

Metadata guardrails

Metadata activation now enforces strict safety checks before a slot flip:

• Canonical partitions are compacted to blocks.typeKeys references before evaluation; expanded blocks.types payloads are only used for discovery.
• Editor metadata is encoded when authored depth exceeds the storage budget of 10, then certified at persisted depth 13 and hard-failed at 14.
• Canonical partitions hard-fail above 750,000 bytes per partition or 2,500,000 bytes total.
• Canonical and materialized rows are validated against byte and depth guardrails.
• Activation aborts if any row shape, fingerprint, count, depth, or byte invariant fails.
• Failed activations keep the previously active slot unchanged.

Depth preflight is contract-driven and reports:

• maxProjectedEditorRowDepth for encoded editor-row depth certification
• depthHeadroom (16 - maxProjectedEditorRowDepth) to track runtime ceiling margin
• encodingAppliedCount showing how often deep branches were encoded
• topDepthEntities (top 5) with projected depth and projected bytes per entity
• projectedCanonicalPartitionBytesMax for the largest projected canonical shard
• projectedCanonicalTotalBytes for the combined canonical payload size
• projectedCanonicalPartitionCount for the number of projected canonical shards
• cycleErrors when block graph cycles are detected during preflight
• hardErrors when any guardrail would block activation

Use these diagnostics to reduce shape complexity before cutover. Do not bypass guardrails.

Summary cards

Four summary cards at the top provide a quick overview:

Collections table

An expandable table lists every registered collection with:

Expanded details

Click any collection row to expand and view:

• Description and group metadata
• Upload configuration (if applicable)
• Versioning status
• Active fields table -- name, label, field type, and sort order for each active field
• Archived fields table -- highlighted with red styling and strikethrough text
• Relationships table -- target collection, relationship type, field mapping, and status

Globals table

The globals table follows the same structure as the collections table, with expandable rows showing field details.

Expand via URL

Use the expand query parameter to deep-link to a specific collection or global:

/admin/diagnostics?expand=posts          # Expand the "posts" collection
/admin/diagnostics?expand=global:settings # Expand the "settings" global

Use cases

• Debugging schema mismatches -- identify when metadata is stale after schema changes
• Tracking archived fields -- see which fields have been removed from the schema but still have metadata records
• Verifying seed operations -- confirm that vextro-sync ran successfully and all collections are registered
• Inspecting relationships -- view how collections reference each other through relationship fields