AutopilotMonitor/docs/drift-guards.md

type, title, description, resource, tags, timestamp

type	title	description	resource	tags	timestamp
Concept	Drift Guards — SignalR Names, RowKeys, Wire DTOs, Tool Vocabularies, Config Sections, Scoped Routing	The 2026-08 fragility-audit follow-up contracts that turn formerly hand-synchronized mirrors into enforced ones — SignalR message-name catalog, the inverted-tick RowKey codec, tombstone table tagging, typed wire DTOs with generated TypeScript interfaces, the MCP's generated tool vocabularies with their inline-enum ratchet, per-section config PATCH, and the web's scoped-endpoint builders.	/src/Backend/AutopilotMonitor.Functions.Tests/TypedResponseGuardTests.cs	contracts guard-tests signalr web	2026-08-31T00:00:00+02:00

Drift Guards

Follow-up to the 2026-08 fragility audit (see Lifecycle Manifests & Session Scope Resolution for the earlier rounds). Each section below replaces a hand-synchronized mirror with an enforced contract: a change on one side now fails a build, a type check, or a test on the other side.

Schema

SignalR message names — one catalog, typed on both ends

Constants.SignalRMessages (Shared) is the complete catalog of SignalR target names. Backend senders (output bindings and the imperative SignalRNotificationService) reference the constants; the hub name is SignalRGroupHelper.HubName. The catalog is exported into shared-manifests.json (signalRMessages section) by SharedManifestParityTests, and the web's SignalRContext.on/off type their event name against the generated union (lib/signalrMessages.ts) — subscribing to a name the backend never sends is a tsc error, not a silent no-op. newevents is the one legacy lowercase name; it is a persisted wire name, do not "fix" the casing.

Inverted-tick RowKeys — one codec

RowKeyCodec (Functions/Helpers) is the single encoder/decoder for rev(t) = MaxTicks - t.Ticks RowKeys. Every writer routes through it; the persisted per-table shapes (D19 standard, AuditLogs !-prefix, UserActivity's legacy D20 width, ConfigurationBackups' 28-char truncation) are pinned by RowKeyCodecTests and must never change — a width/prefix change reorders live tables against their existing rows. BusinessTimestamp keeps the OData clause builders and delegates decode to the codec.

Tombstone rows carry their table

DeletionRowDump.Table names the source table on FINAL (Tombstone) rows — the one step that mixes two tables while DeletionStep.Table is null. DeletionTombstoneTables.Resolve is the only consumer-side resolution (delete + restore + dry-run); the historical Contains('_') RowKey-shape heuristic survives solely as the fallback for manifests written before the field existed and must outlive one full manifest-retention cycle.

Wire DTOs — generated interfaces, zero anonymous success bodies

Every HTTP success body is a flat class in AutopilotMonitor.Shared.Models implementing the IApiResponse marker (2026-08-31, feat/typed-api-contract — migrated from the 44 OkAsync(new { … }) + 134 raw WriteAsJsonAsync(new { … }) sites the 2026-08-13 audit froze). Three layers enforce it:

• Compile time: the only OkAsync/CreatedAsync/JsonAsync overloads constrain on IApiResponse — an anonymous object cannot satisfy the constraint. Error bodies (first key error/message, or literal success = false) stay anonymous by design.
• TypedResponseGuardTests (successor of OkAsyncBaselineGuardTests): both per-file baselines are EMPTY — any anonymous success body, through the helpers or raw WriteAsJsonAsync, is a straight failure. A reflection fact keeps every IApiResponse implementer flat (System.Text.Json serializes derived properties before base ones — key order is wire contract; MCP hands raw JSON to an LLM) and inside the Shared assembly.
• *WireParityTests: each migrated site carries an ordinal old-anonymous-literal vs. new-DTO serialization proof (production ApiJsonOptions), including a null case per key that WhenWritingNull omits.
• Object-slot ratchet (2026-08-31 typisierung follow-up): a reflection walk over the reachable wire-type graph fails on any object / collection-of-object property outside ObjectSlotBaseline (sole entry: RuleDryRunCondition.Evidence, heterogeneous by design). [ProjectedItems] slots and dictionary VALUES are exempt. The former deliberately-untyped slots (RuleDryRun trace, HealthCheck, GlobalNotificationDto, TenantConfigFieldSchema, maintenance run reports, MetricsSummary items, auth/me, auth/mcp) are concrete Shared types now. The raw table entities left the wire entirely in the same pass: global-admins, tenant-admins and preview-whitelist serve flat rows (GlobalAdminRow / TenantAdminRow / PreviewWhitelistTenantEntry) WITHOUT partitionKey/rowKey/eTag/timestamp — a deliberate wire change pinned by exact-JSON shape tests instead of parity facts.

The DTO rules: declaration order == wire order; a property is nullable exactly when a site can emit null (the key then vanishes — never add non-null defaults that would invent a key); preformatted strings (.ToString("o"), enum .ToString()) stay string; fields= projections stay IReadOnlyList<object> tagged [ProjectedItems(typeof(Item))]; raw table rows stay verbatim-keyed dictionaries (no DictionaryKeyPolicy — dictionary KEYS never run through the camelCase policy, and dictionary VALUES keep explicit nulls, both pinned by tests).

SharedManifestParityTests (schemaVersion 2) reflects the full graph — every IApiResponse implementer plus [WireContract]-marked payload types, transitively closed by WireTypeManifestBuilder — into the types section of shared-manifests.json, carrying C# <summary> texts. The web codegen (npm run generate:manifests) emits utils/wire-types.generated.ts (one interface per object, one string union per enum, JSDoc from the summaries); the hand-written types/session.ts / types/enrollment.ts / types/adminConfig.ts re-export from it. Freshness is pinned by the vitest suite and the shared-manifests-in-sync CI job. Unmappable shapes (non-string dictionary keys, foreign BCL classes) fail the manifest build instead of degrading to unknown.

Tool vocabularies — the MCP derives them, it no longer retypes them

Wire TYPES reached the MCP from day one (src/generated/wire-types.generated.ts, the same codegen output the web gets). Vocabularies did not: types are erased at runtime and a z.enum([...]) needs values, so every MCP tool schema hand-typed its own copy of statuses, severities and categories — with nothing to compare against. The copies drifted exactly as you would expect: search_sessions offered 5 of 8 session statuses (no AwaitingUser, no Incomplete), both event readers offered 4 of 6 severities (no Debug, no Trace), and get_ops_events named 6 ops categories while the backend wrote 7. None of that surfaces as an error — the tool just quietly cannot ask for the missing value.

The vocabularies now ship as VALUES. MCP_VOCABULARIES in the codegen maps manifest sections onto src/generated/wire-vocabularies.generated.ts (export const SESSION_STATUSES = [...] as const plus its union type); the tool schemas do z.enum(SESSION_STATUSES) and descriptions interpolate the list instead of spelling it. Freshness is pinned twice: wire-types-freshness.test.ts compares the committed file byte-for-byte against a fresh codegen run, and the shared-manifests-in-sync CI job diffs it after regenerating.

vocabulary-drift.guard.test.ts is the ratchet that keeps it that way: every inline z.enum([...]) left in src/tools/*.ts must be on a baseline that names why it has no backend owner (MCP-local knobs like depth: fast|deep, plus three free-string columns — rule type, connection type, CVE risk — that have no C# constants class yet). A new hand-typed list fails until it is derived or reviewed onto the baseline, and a stale baseline entry fails too.

Ops event types got the missing owner: they were bare literals at the OpsEventService call sites, so nothing could enumerate them and both the portal alert-rule catalog and the MCP had to retype the list. OpsEventTypes (Shared) now declares all 77; the write sites use the constants (a raw literal fails OpsEventTypeDualRegisterTests), the manifest exports them, and get_resource(name="ops_event_types") serves categories + severities + types to the model from the generated copy.

Backend-internal lists follow the same rule: a list that enumerates a constants class IS the class. TableOpsEventRepository.AllCategories is OpsEventCategory.All rather than a retyped copy — the copy had gone stale and silently hid every Platform (Azure Monitor) event from the paged cross-category read while the unpaged path still showed it.

Tenant settings — per-section PATCH

The web's Settings sections no longer PUT the full ~92-field configuration. Each section's exact write surface lives in app/settings/sectionFieldMap.ts (owned fields plus documented alsoWrites write-throughs); saveConfiguration diffs those fields against the loaded config and PATCHes only the changes through PATCH config/{tenantId}/fields — the transactional endpoint (CAS + fail-closed backup + exactly-these-fields verify + auto-rollback) that previously served MCP only. The policy line is TenantAdminOrGA; a tenant admin runs on the stricter TenantConfigCallerTier.TenantAdmin whose deny-list turns GA-only fields into explicit 400s. Deploy order: backend before web. sectionFieldMap.test.ts pins field↔section ownership (each field exactly one owner, all fields on the model, none server-denied); backups/revert stay GlobalAdminOnly.

Scoped endpoint routing — one decision object

lib/scopedApi.ts owns the tenant/global endpoint-pair choice: pages pass their scope hook object (routeGlobal, selectedTenantId, effectiveTenantId) instead of hand-rolling routeGlobal ? global(..., sel || undefined) : tenant(tid, ...) with the tenant parameter at a different position per pair. useGlobalAdminScope is now a thin projection over useAggregatedAdminScope (one hook, aggregated as a mode) via the pure resolveConcreteScopeView. lib/scopedFetch.ts adds the shared JSON+ok-check fetch layer. lib/navVisibility.ts extracts the sidebar's roles × nav-config × guard logic; its matrix test also ratchets the known "sidebar shows it, guard bounces it" mismatches (plain Operator and GlobalReader vs. /settings — pending a user decision).

Examples

Renaming a SignalR message end to end: change the constant in Constants.SignalRMessages → AM_WRITE_SHARED_MANIFESTS=1 dotnet test --filter SharedManifestParityTests → node scripts/generate-shared-manifest-types.js → tsc now flags every stale web subscription literal.

Adding a field to a Settings section: add it to the section in sectionFieldMap.ts (tsc validates the name against the manifest), wire the form state into the updatedConfig construction in TenantConfigContext, and extend the expected-fields list in sectionFieldMap.test.ts.

Citations

• src/Shared/AutopilotMonitor.Shared/Constants.cs — SignalRMessages catalog
• src/Web/autopilot-monitor-web/scripts/generate-shared-manifest-types.js — MCP_VOCABULARIES, the vocabulary codegen
• src/McpServer/autopilot-monitor-mcp/src/__tests__/vocabulary-drift.guard.test.ts — the inline-enum ratchet
• src/Shared/AutopilotMonitor.Shared/DataAccess/OpsEventTypes.cs + OpsEventTypeDualRegisterTests.cs
• src/Backend/AutopilotMonitor.Functions/Helpers/RowKeyCodec.cs + RowKeyCodecTests.cs
• src/Shared/AutopilotMonitor.Shared/Models/Deletion/DeletionManifest.cs — DeletionRowDump.Table, DeletionTombstoneTables
• src/Backend/AutopilotMonitor.Functions.Tests/TypedResponseGuardTests.cs + WireTypeManifestBuilder.cs + the *WireParityTests files
• src/Shared/AutopilotMonitor.Shared/Models/CommonApiModels.cs — IApiResponse, [WireContract], [ProjectedItems]
• src/Web/autopilot-monitor-web/utils/wire-types.generated.ts (via scripts/generate-shared-manifest-types.js)
• src/Web/autopilot-monitor-web/app/settings/sectionFieldMap.ts + __tests__/sectionFieldMap.test.ts
• src/Web/autopilot-monitor-web/lib/scopedApi.ts, lib/navVisibility.ts, hooks/concreteAdminScopeView.ts
• Version Contract — the web /version.json stamp + deploy verify added in the same round