Support backlog/SLA pilot data contract

Status: engineering contract for operator review. No real customer-support export has been supplied or validated. The current Decision Lab fixture is synthetic.

Decision to be supported

The pilot compares a frozen staffing baseline with an explicitly proposed schedule for one named support queue. The primary stock is unresolved tickets at the end of each UTC day. The daily flows are created and resolved tickets. Secondary measures are resolved tickets within the configured SLA day threshold, overdue pending tickets, and staffing cost. The simulator assumes FIFO service and integer tickets, staffed agents, and per-agent daily capacity. A staffing comparison is an exploratory scenario until prospective forecasts, held-out skill, and a measured action are available.

An operator must confirm the queue identity, whether agents represent full-shift equivalents, how transfers/reopens are normalized, the SLA clock and exclusions, fixed extra capacity, cost units, allowable interventions, and the threshold at which a backlog is unacceptable. Those choices must be written into a versioned model and policy before any operational review. No defaults in the synthetic fixture imply approval of these definitions.

Required export

The local importer accepts SupportPilotExport JSON plus a separate QueueModel JSON. Every ticket row has one stable ticket_id, the exact queue_id, created_at_utc, and optional resolved_at_utc. Every staffing row has the same queue_id, a UTC midnight day_utc, an integer agent count, and integer fixed_extra_capacity. The envelope names an immutable snapshot and baseline scenario, UTC window start and data cutoff, seed, horizon, and source-version hash. See the executable fields in decision_ingest.rs and the local import command in decision_cmd.rs.

Field or rule	Required meaning	Current validation
queue_id	One upstream queue, identical on every ticket and staffing row	Nonempty, trimmed, at most 128 bytes, exact row match; the importer also checks the operator-supplied expected ID
ticket_id	Stable identity after an explicit transfer/reopen normalization rule	Nonempty and unique within the export; at most one creation and one resolution per ID
Event times	UTC creation and optional UTC resolution	RFC 3339 UTC; resolution cannot precede creation or exceed the cutoff
window_start_utc and horizon_days	Complete UTC days to reconstruct	Start is UTC midnight; 1–366 days in the parser, with one staffing row for every day; the synthetic dashboard creator uses 21–90 days
data_cutoff_utc	Latest source event visible to this snapshot	Must cover the entire declared horizon; source events cannot be later
Staffing	Agents and fixed extra resolution slots planned for each day	Exactly one row for each in-window UTC midnight; observed resolutions cannot exceed observed stock or zero-agent fixed capacity
source_version_hashes	Identity of the exact ticket/staffing rows	Local import requires one SHA-256 matching its serialized [tickets, staffing] source bytes
QueueModel	Service capacity, SLA day threshold, staff cost in cents	Separate immutable model; simulation checks stock and capacity invariants before storage

The local pilot import currently limits the export file to about 2 MiB and the separate model file to 16 KiB. The retained causal artifact receives an explicit future retention deadline. A gateway background task enforces that deadline hourly across every scope, revoking expired ticket source bytes without an operator having to run duduclaw decision-scrub-expired-ticket-sources or press the dashboard scrub button; reading an expired blob still revokes it immediately. A scope the sweep cannot process is logged and retried on the next pass. The importer also writes exact source bytes to an owner-readable --source-output file; that separate file has no automatic expiry and its owner must securely retain or delete it. The digest proves byte consistency in this local workflow; it does not authenticate the upstream system. The producer must supply an authenticated connector identity and a trustworthy export timestamp before a real-data claim is made.

Dashboard operator upload

The instance-admin Decision Lab accepts one operator-provided export, one QueueModel, and one explicit alternative StaffingScenario as a bounded JSON upload. The selected tenant and ACL, expected queue ID, source lineage, and future UTC retention deadline are part of the request. The baseline comes from the observed staffing rows; the alternative must have a distinct ID and an explicit daily staffing and extra-capacity schedule for the same horizon. The server checks both scenarios against the same frozen snapshot before making a completed import selectable. It stores the canonical ticket/staffing source in the scoped causal store and returns only source digests, artifact and scenario IDs, replay hashes, optional held-out diagnostics, and limitations. Ticket rows are not returned to the dashboard.

Uploaded rows are operator-provided local evidence. A matching queue label, source digest, and retention deadline establish local consistency and access scope; they do not authenticate the upstream support platform or show that the model fits its process. An interrupted import may leave immutable staged records, but only an active source-bound completed receipt can be listed, compared, or replayed as an uploaded pilot. Repeating the same request can finish that receipt; conflicting use of an existing snapshot or model ID is rejected. Importing does not commit a staffing action.

Ticket-SLA shadow sources are uploaded through the same dashboard but under their own limit. One inline opening or day-end ticket export may be at most 2 MiB, and the request itself is capped at that size plus 64 KiB of JSON envelope headroom; a larger request is rejected with a payload-too-large response before any parsing. The browser refuses a file over 2 MiB, a file that is not valid UTF-8, and a file that is not JSON before anything is sent. Larger exports must use duduclaw decision-shadow-sla-forecast or duduclaw decision-shadow-sla-score, which register the source artifact locally; the dashboard then loads that saved record by its artifact ID. Inline uploads still require an explicit future UTC retention deadline, and the stored ticket rows are never returned to the dashboard.

After both imported scenarios reproduce their exact replay hashes, an administrator can request human inspection of one run through the existing approval inbox. Request and status checks reread the active source-bound receipt; the resulting review is an inspection record only. It does not authenticate the upstream export, validate the capacity model, or authorize a staffing change.

Decision Lab can recompute historical engineering diagnostics and paired empirical resampling from that same active uploaded source. The report marks operator uploads separately from canonical synthetic fixtures. A short window or an unidentified capacity produces an explicit unavailable diagnostic rather than an invented fit; empirical resampling can still use a declared capacity range when the training prefix does not identify one. The two scenario runs reuse common draws and remain descriptive stress tests. Neither a review-screen candidate nor its probabilities establish an intervention effect or a prospective SLA guarantee.

The Decision Lab ticket-event comparison replays both saved scenarios from the exact active ticket/staffing source using FIFO service in fixed 09:00–17:00 UTC slots. The admin endpoint accepts only the scoped snapshot, model, and scenario IDs; the server resolves and rechecks the source, saves both event-run manifests, and returns aggregate within-SLA counts, resolved-ticket wait p50/p95, final backlog, costs, and replay/source/engine hashes. It never returns ticket IDs or rows. The fixed shift and service-rate assumptions are exploratory; unresolved ticket waits are censored from the reported quantiles. A Dashboard result is a point-in-time replay, not an authenticated upstream observation or a calibrated staffing forecast.

After a saved empirical run exists, Decision Lab can request a fresh brief that links this exact event-run pair by both replay hashes. The request contains no ticket text. The server resolves the source under the same scoped completed pilot, recomputes both event runs, verifies the supplied hashes and empirical run against the selected snapshot/model/scenario order, then rereads the current source before returning the brief. The event section remains descriptive, separate from the daily KPI and observational causal effect sections. An event pair alone cannot become a calibrated effect or a staffing approval.

For a completed operator upload with an available stored ticket-SLA holdout, Decision Lab can also request a brief with that exact receipt-bound holdout ID. The server uses the active receipt and source bytes to reload the immutable holdout and checks its stored digest, snapshot, model, and baseline; no source bytes are accepted from the browser. This attachment can stand alone or accompany the empirical and event sections. Its observed-versus-conditional-predicted SLA totals use actual later arrivals and staffing, so they assess historical queue-rule fit without validating prospective demand or an intervention effect.

Decision Lab can validate historical one-day-ahead backlog forecasts for a complete synthetic or uploaded pilot. The browser sends only the exact scoped pilot pair; the server resolves the active source and uses fixed 14-day training, seven saturated-day, and 14-point calibration requirements. When the source supports a backtest, the server stores an immutable source-bound validation record and returns its ID, digest, evaluation-day count, arrival error, backlog error against no-change, weekly seasonal, and mean-change baselines, and separately observed rolling and fixed-prefix interval coverage. Too few days or unidentified capacity produces an explicit unavailable reason and no record ID; a record may exist while interval coverage remains unavailable. The Dashboard requires an explicit choice before attaching this record to a brief, and the server reloads and revalidates its source, digest, snapshot, and baseline after composing the brief. The attached section remains separate from simulated scenario KPIs. These are retrospective observations using later actual demand and staffing, not prospective calibration, authenticated upstream evidence, or a staffing intervention effect.

The admin Dashboard also supports the immutable outcome-model candidate workflow by exact saved IDs. An eligible saved outcome-fit review screen can create a simulation-only capacity candidate; the Dashboard can reload it, save or reload a later-snapshot comparison with the parent model, and save or reload a score against a later observed-outcome journal. Each server call revalidates the scoped stored records, active source versions, candidate and comparison digests, and the local creation order required before scoring. Responses contain aggregate KPIs or decimal-string error sums, status, hashes, and limitations; they exclude per-day observations and ticket rows. A local comparison or score does not authenticate the outcome producer, promote the candidate into the live model namespace, or authorize staffing action.

The Dashboard exposes the preceding calibration and review steps as admin-only, exact-scope calls. An operator can fit a saved observed outcome with a declared training prefix and saturated-day minimum, inspect the candidate, parent, and no-change held-out backlog error sums, and save or reload a review screen with explicit saturated and holdout thresholds. The screen shows queue identity, local pre-observation timing, failed checks, immutable record hashes, and bounded source digests. Only a screen with no failed checks can be sent to the candidate panel or used to request a time-limited human inspection receipt; the receipt’s pending, approved, denied, or expired status is tied to that exact screen and rechecked against active sources. Approval records inspection, not model activation or staffing authorization. All observed rows and ticket identifiers remain server-side; error sums travel as decimal strings to preserve u128 values.

For prospective aggregate shadow checks, an administrator predeclares a queue, lineage, UTC policy window, and issue deadline before the first target day. Each day’s training export contains only prior observations and known opening backlog and staffing; its forecast must be committed on the target UTC day within that deadline. A separate observed-day export may be scored only after the day ends. The Store freezes one forecast and score per lineage/day, rechecks the source bytes and timing on reads, and reports missing or revoked days as incomplete. An assessment covers every due day; a saved review screen can pass only with a complete 21-day minimum, strict backlog skill against each baseline, enough fixed-prefix interval coverage, and no recent drift. The human receipt permits inspection of that exact saved screen only. Small UTF-8 JSON exports may be submitted directly to the admin Dashboard under its 16 KiB request cap; larger files can be committed with the existing shadow CLI commands and their resulting forecast or score loaded in the Dashboard. Rejected inline uploads are scrubbed when they created a new source artifact; retries that reuse an already committed source keep that source intact. The aggregate shadow path does not evaluate ticket-level SLA outcomes. Policy handoff and score corrections are separate CLI operations, and upstream source authentication and an operational action gate remain required for live use.

The aggregate training source is an ObservedOutcomeExport JSON object with queue_id, window_start_utc, observed_through_utc, and observed_days. Each day has arrivals, backlog_start, resolved, backlog_end, agents, and fixed_extra_capacity; sla_days and resolved_within_sla_by_day may be null for this aggregate path. The training window must end at the target UTC midnight and contain at least the policy’s declared minimum days. The later observation export uses the same shape with exactly one day from target midnight to the next midnight. The forecast request separately declares the already known opening_backlog, planned_agents, and planned_fixed_extra_capacity. Extra fields inside training days are rejected, including a hidden target-day outcome.

When an empirical run is attached to a comparison brief, the backend rereads its single active, scoped causal source and derives a typed source class from the artifact kind and exact version hash. The brief and Dashboard label canonical synthetic fixtures and operator uploads separately; missing or ambiguous provenance stays unclassified. An uploaded brief describes resamples from historical operator-provided rows without claiming authenticated upstream identity or calibrated coverage.

Validation and evaluation sequence

1. Confirm process definitions with the queue owner and normalize source events before export. Reject mixed queues, partial labels, duplicate IDs, missing staffing days, or impossible stock flows.
2. Retain the exact source bytes and version, bind them to a snapshot, and reserve a time-ordered training prefix. Capacity is identified from saturated days only; unidentifiable service parameters stay as explicit ranges.
3. Run rolling one-day backlog and ticket-level SLA diagnostics against no-change, weekly seasonal, and seven-day mean baselines. Report the number of evaluated days and absolute errors for each method. A fixed early residual band must be evaluated only on later days; show coverage and drift without calling it a calibrated future interval.
4. Commit shadow forecasts before target-day outcomes, then score complete, authenticated later observations under the same queue and model. Preserve corrections as revisions. Missing, invalid, or revoked days withhold the whole-window skill claim.
5. Only after prospectively observed skill, operator criteria, and a separate human review should a limited staffing action be considered. The Decision Lab endpoints remain read-only and do not issue staffing changes.

The synthetic fixture verifies the software path and reproducibility. It cannot establish real forecast accuracy, causal staffing effect, source authenticity, or calibrated uncertainty.