feature/analytics-suite #7

Open
Patrick wants to merge 41 commits from feature/analytics-suite into main
Owner
No description provided.
The scan lane only skipped a .fs whose pending_faxes row was still
pending. So when RingCentral reported SendingFailed, the row flipped to
failed, the lane ran before MoveFailedFaxFiles had shifted the files,
and the fax went out a second time — then reported "payload missing"
once the .cap had reached fail/. The dedupe now skips any row that is
not an explicitly retried failure; retried_at is what distinguishes
"the operator asked for this" from "it just failed".

resolveFax() recorded neither failure_reason nor failure_stage, so a fax
the provider accepted and then failed to send landed on the failures
list with no reason and — because Send Again was gated on
failure_stage === 'submission' — no way to resend it. Both the poller
and the webhook now record the reason and the stage, and Send Again is
offered for either, since the spool files are in fail/ regardless.
FaxRetry still refuses the one case that genuinely cannot be retried,
a payload that has gone.

FaxFailAlert throws when no failure notification address is configured,
and it ran before the pending_faxes update, so an install that never
set one left every failed fax pending for ever and re-failed it on each
run. Alerting is now wrapped so it cannot decide whether a fax resolves.

Tests pin the whole lifecycle: delivered, fresh failure, retried
failure, reused .fs filename, fan-out, missing payload, and an
unconfigured alert address.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Draft specification for a toggleable analytics module covering call volume,
trends, account patterns and message metrics, phased across managers,
supervisors, client reports, agents and billing.

The governing constraint comes from why the previous Analytics area was
removed in 7ed22e4: its numbers were our own interpretations of what each
metric meant, with nothing authoritative behind them. Amtelco does not
publish those definitions in prose, but it ships them as SQL inside its
Crystal reports — 269 of them, 266 carrying a full query. So every metric in
this module traces to a named Amtelco report, or ships visually distinct and
labelled as ours with its formula shown.

That already exposes a real divergence. Aggregate/AnswerTime averages
UnSelRing + UnSelAutoHold + UnSelHold across every call; Genesis Service
Level Data computes FLOOR(SUM(TimeToAnswer) / SUM(Answered)) over answered
calls only. Both are defensible, only one is Amtelco's, and they could never
have agreed. Amtelco's service level is also quick calls over offered — a
call answered inside QuickCallMax, default 12 seconds — rather than the
industry 80/20.

Scoped deliberately narrow: the existing dashboard statistics are left alone
so their values do not change underneath people, and the module is Genesis
only, with Infinity, MDR and CTE out of scope. Infinity handling elsewhere in
the application is untouched.

The schema reference is committed alongside because writing stat queries
against a database none of us can reach, without column names or row counts,
is how the first attempt went wrong.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Works through the inline review notes and settles what they decided:
metrics with no Amtelco equivalent ship labelled as ours rather than being
withheld, with the industry-standard 80/20 service level as the first of
them alongside Amtelco's quick-calls-over-offered figure; ECharts confirmed;
report parameters are per report; acceptance is by UAT rather than a
reconciliation exercise.

Adds report aliasing, so an installation can show "Answer Time Performance"
where Amtelco says "Genesis Service Level Data" without forking a
definition. The canonical name stays visible and the override is display
only, so aliasing cannot quietly relabel one metric as another.

On dark mode, keeps the design system as it is. A Tailwind variant never
reaches either renderer — ECharts needs real colour values in JavaScript and
server-rendered SVG needs literal fill and stroke attributes — so the
question a chart actually asks is what colour a token is right now, which
the existing redeclaration answers and a variant could not.

Closes two gaps the review did not cover. Time zones get their own section:
buckets are computed in the switch time zone, never UTC or the viewer's, and
every report states which zone it used. CallLogFilterTimezoneTest already
documents five hours of skew on a Central switch that was invisible on a UTC
one, and a daily total wrong by one shift is far harder to spot than a filter
that opens empty. Account scoping now applies from Phase 1 rather than only
the client-facing phase, enforced in SQL, because an operation-wide total
otherwise leaks the size of accounts a team cannot open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The time zone section had this wrong. The switch is the anchor — every stat
stamp is written against the zone the Genesis switch is configured for — but
presentation belongs to whoever is reading: an internal report converts to
the reader's own profile zone, and only a client-facing report uses the
per-client TimezoneOffset carried in the data. Those offset columns are
client offsets, not a hint about how the stamp itself is stored, so internal
reporting never touches them.

That makes daily totals reader-dependent, which is correct but has to be
visible, so every report states the zone it was computed in. Billing is the
exception and is always computed in the switch zone: an invoice cannot change
depending on where the person running it lives.

Metrics are now aliasable on the same terms as reports, since a column headed
"Sys SL %" helps a client no more than "Genesis Service Level Data" does.
Both sets of overrides live at System → Analytics, display only, with
canonical names always visible.

Adds reference/amtelco-report-candidates.md: all 264 report docs classified
by the tables their SQL actually touches rather than by filename — 161
Genesis, 78 switch-agnostic, 25 Infinity excluded — grouped into proposed
phases with a one-line description each, as a checklist to prune. The phase
contents in the spec are guesses from filenames and this is the cheapest
thing to correct before any code exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One blank line between entries; the list was unreadable as a solid block
while reviewing it. Review marks, strikethroughs and notes are untouched —
the non-blank lines are byte-identical to before.

Also answers the inline question. Call Detail and Call Detail Minutes are the
same query: the docs differ only in title and .RPT filename, so the minutes
variant is a Crystal layout that formats durations differently. That is a
display option, not a second report.

Checked whether this generalises, since it would be a useful pruning lever.
It mostly does not: of 20 variant pairs where the base report also exists,
only three share identical SQL. The rest — including most -minutes variants —
do the conversion or the grouping in the query and are genuinely separate
reports.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Account Statistics Detail and its minutes variant are identical SQL, 766
lines each, so they merge behind a duration-units toggle like Call Detail.

Account Statistics versus Client Statistics do differ substantially, but
Account Statistics subsumes the other: V2.9.1 against v1.4.0, 1351 lines
against 215, and every table Client Statistics touches it also touches while
adding the per-channel delivery detail, dialouts, logouts and the directory
joins. Take it as the authoritative definition, but build the channel
breakdown only for email, WCTP and fax — the other seven channel tables are
empty on this installation and would render as columns of zeros.

Agent Permission Groups and its searchable variant differ only in the
parameter: one takes an agent name with ALL as the show-everything sentinel,
the other a LIKE pattern with %%. Same tables, same output, so that is an
optional filter on one report.

IS Messenger Detail moved to the supervisor section as requested, which
empties the Genesis unassigned bucket.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds a sixth phase for reports that describe how something is set up, and
what changed, rather than how the operation performed. Different audience,
different cadence, no charting, and in the pure-setup cases no date range at
all — grouping them with the performance phases would put a static
configuration dump next to a service-level trend and imply they were the same
kind of thing.

Eighteen reports move: the agent, client, directory and ACD setup snapshots,
the maintenance and change audits, and on-call assignments. The change-audit
members keep date parameters since "what changed in this range" is a real
question; the setup snapshots take none.

Unassigned Shift Reminder Emails is struck as a report. It is Unassigned
Shifts delivered only when it finds something, so the spec now carries that
as a scheduling option — which also covers "tell me when abandons exceed X"
later without inventing an alerting system.

Entry count and every review mark are unchanged: 265 entries before and after.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
It is a report, not a delivery mechanism. The doc says so plainly: "a list of
all Unassigned Shift Reminder Emails for all clients grouped by subject",
with no parameters — a static configuration listing, which is squarely phase
6. Restored as a report and the wrong note removed. I inferred that one from
the filename instead of reading the doc.

The conditional-delivery option stays in the spec on its own merits, since an
exception report that mails an empty page nightly trains people to ignore it.
It just is not what this report is.

Also records that this is the only report doc of 264 with no SQL block — the
other two files without one are index and navigation, which are not reports.
Its definition has to come from the .rpt or the schema rather than off the
page, which matters given every metric is supposed to trace to a written
definition.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Analytics metrics are Amtelco's T-SQL — #temp tables, STRING_AGG, DATEDIFF,
WITH (NOLOCK) — none of which SQLite can parse. Without a real SQL Server a
test can only assert that we generated the query we meant to, never that the
query returns the number Amtelco's own report returns. The previous analytics
area was deleted for producing figures nobody trusted, so that is the only
distinction that matters here.

Adds a SQL Server service to docker-compose and an intelligent_testing
connection pointing at it. The Sail image already carried sqlsrv, pdo_sqlsrv,
msodbcsql18 and mssql-tools18, so nothing was needed there.

Tests\Support\IntelligentTestSchema builds a cut-down Intelligent Series
schema from the snapshot committed at docs/specs/reference/table-columns.tsv,
so a test queries tables with production's columns and types rather than ones
invented to suit it. Only the handful of tables a test asks for are created;
production has 312 and 27 million rows in statCallTracker alone.

Parsing that snapshot is the part that can silently be wrong, so it is tested
without a database. Commas separate columns and also appear inside types like
numeric(18,0), which affects twelve tables including sysConfig and
statScriptTracker, so splitting happens only at paren depth zero.

Tests needing the server skip rather than fail when it is not up: most of the
suite has no business requiring it, and the extension only exists inside the
Sail image. The Integration suite is registered so those skips stay visible
instead of rotting outside the default run.

The harness test demonstrates the shape every metric test will take — seed
known rows, run the real T-SQL, assert a hand-computed number — using
Amtelco's own definition of live traffic as Kind IN (1,2).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The container was up and the login worked; the database simply did not
exist. SQL Server has no equivalent of the MySQL image's MYSQL_DATABASE, and
the official image does not honour a docker-entrypoint-initdb.d, so a fresh
container comes up with only the system databases.

The harness now connects to master and creates it if absent, which keeps
`sail up -d mssql` as the whole of the setup instructions rather than adding a
manual step everyone forgets once. The name is pattern-checked before being
interpolated, since DDL cannot take a bound parameter.

Also separates the two failure modes in the skip messages — the server being
unreachable and the database failing to open were both reported as the
former, which sent the reader off to start a container that was already
running — and purges the connection after creating the database so a handle
opened beforehand does not keep reporting the original error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three failures from the first run against SQL Server, each worth keeping.

statCallEnd has 44 NOT NULL columns out of 51 — every ring, talk, hold, patch
and conference counter, including ones no metric reads. Requiring a test to
name all of them to insert one call would make these tests unwritable, and
would bury the two or three columns a test is actually about. Seeding now
fills the rest from the snapshot with neutral values, so a test states only
what it means. Zero rather than a recognisable sentinel, because these
columns land inside SUM and AVG and a 999 would quietly corrupt an assertion.

Amtelco's reports are multi-statement batches — temp table, inserts, then a
select — and the driver was treating each "N rows affected" message as a
result set, failing the fetch with "the active result for the query contains
no fields". SET NOCOUNT ON is applied once to the session so the SQL under
test stays exactly as written.

The column the harness asserted on was unSelRing; production spells it
unselRing. Guessing at casing was the wrong instinct when the snapshot is
committed and authoritative.

One bug the new tests caught on their own: neutralValue split the type on its
opening paren, which left "datetime not null" and matched nothing, so every
column defaulted to an empty string — integers included. The test that should
have caught it reported "risky, no assertions" rather than failing, so it now
asserts the counters really are integers and cannot pass vacuously again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every report in the Amtelco set opens with DECLARE, assigns its parameters,
builds one or more #temp tables, and only then selects. DB::select() fetches
the first result the driver reports for such a batch, which belongs to the
DECLARE and carries no columns, so it failed with "the active result for the
query contains no fields" — the SQL was fine, it was being read one result
too early. SET NOCOUNT ON suppresses the "N rows affected" counts but not
these, so the session setting alone did not help.

runIntelligentQuery now prepares the batch and walks forward to the first
result that has columns, with runIntelligentBatch exposing every result set
for the few reports that select more than once. Bindings go through the
connection's prepareBindings, since report parameters are nearly all dates.

This is what lets a metric test paste in a report's SQL near-verbatim and
assert on the number it returns, rather than on a reimplementation of it.
Two tests cover it: one mirroring a real report's DECLARE/SET/#temp/SELECT
shape against the statCallEnd snapshot, one for multi-select batches.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The previous Analytics area was removed because its figures were our
interpretations rather than anything Amtelco documents. This is the answer to
that: every metric quoted with the exact expression Amtelco uses, cited to the
report doc and line it came from, so a number can be argued from their
arithmetic instead of our reading of it.

Covers the shared spine — call population and Kind filters, the three distinct
answer times, service level, abandons, interval bucketing, Erlangs, agent
occupancy — drawn mainly from genesis-service-level-data.md and
genesis-traffic.md. All 31 citations were checked against the source files.

The findings that will decide whether our numbers match theirs:

- 75 of 633 aliases are defined differently in different reports. "Assigned"
  ships with two incompatible filters simultaneously: Kind IN (1,2) in the
  service level reports, Kind NOT IN (3,9) in the interval overview and agent
  summary — two kinds versus thirteen, on the same data.
- Agent-level service level drops the @OPT parameter and measures from
  distribution only, so it excludes queue time and is not comparable with the
  overall figure it sits next to.
- Avg Answer Time FLOORs, Avg Sys Answer Time CEILINGs, in the same SELECT.
- Service level's denominator is answered calls, not offered, which is not
  where most of the industry puts it.
- Offered Calls is a sum of three flags, never COUNT(*).
- Abandons are deliberately exempt from the @RINGMIN short-call gate that every
  neighbouring metric applies; Amtelco says so in a comment.
- genesis-traffic buckets to interval start but names the column IntervalEnd,
  and returns a second result set listing zero-traffic intervals.
- QiuckCall is a real misspelling in five shipped reports, consistent within
  each, so they run correctly. Recorded so nobody "fixes" it.

metric-alias-index.tsv carries all 5,113 aliased outputs as alias to doc and
line, as traceability for everything the dictionary does not yet cover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The runnable half of the metric dictionary. Each test copies the expression
Amtelco ships, cites the report doc and line it came from, runs it against one
seeded seven-call scenario and asserts the number by hand. These are the
oracle: the metric classes will be correct exactly insofar as they return what
these queries return. Asserting on query text would prove nothing, which is
how the previous Analytics area shipped figures nobody could defend.

The scenario is built so each metric lands on a different number, since a test
that passes on a coincidence is worse than no test. It covers:

- Offered Calls is 5 while the live row count is 6, because the disconnected
  call is in neither the answered nor the abandoned flags. Asserted as a
  difference, so substituting COUNT(*) as the abandon denominator fails here.
- The @RINGMIN gate drops an answered call that rang for one second but leaves
  both abandons counted, which is the exemption Amtelco notes in a comment.
- Assigned returns 5 under the service level report's filter and 6 under the
  interval overview's, on the same rows. Asserted as not-equal, so the test
  fails if the scenario ever stops demonstrating the conflict.
- Avg Answer Time FLOORs to 3 where Avg Sys Answer Time CEILINGs to 4.
- Service level reads 66.7% over answered and would read 40% over offered.
- A zero quick-call threshold reads as a fake 100%, pinned so the suite is
  forced to render an unconfigured threshold as unconfigured.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two corrections to the spec, both found while building the dictionary, and both
the kind of error the dictionary exists to catch.

There is no single "Amtelco service level". genesis-service-level-data.md emits
three in adjacent columns sharing the SUM(QuickCall) numerator: QuickCall %
over answered, QuickCallAssigned % over assigned, and Sys SL % over
assigned + reassigns + sys abandon. On the same calls they read 66.7%, 50.0%
and 28.6%. The spec previously asserted one definition and described its
denominator wrongly, contradicting the formula printed two lines above it.
Sys SL % is the one closest to the industry 80/20 convention.

@QuickCallMax has no documented default. The spec gave 12 seconds as Amtelco's;
the only values in the corpus are commented-out test lines, 12 in two reports
and 18 in a third. It is operator-supplied, so it has to be configured and
shown, and 0 disables the metric and makes service level read a fake 100%.

Also records that Stat cannot currently execute an Amtelco report at all:
Stat.php:45 uses DB::select(), which fetches the first result of the batch —
the one belonging to the DECLARE, with no columns. Every existing subclass is a
single-statement query, so this has never surfaced, but any metric transcribed
from a report will fail on construction until the runner walks forward to the
first result with columns. Same fix as the test harness. Noted alongside it
that Stat queries in its constructor, so a metric's parameter handling cannot
be unit-tested in isolation, and that Crystal's {?Param} placeholders are not
valid T-SQL and need translating to bindings.

Phases become areas, per the decision to build them together rather than in
sequence. The grouping now organises navigation and access scoping; the only
split that carries weight is configuration-and-change-audit versus metrics.
Report contents are settled from the 119/120 review, so that open question is
closed and six real ones are recorded in its place.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two prerequisites for every metric, neither of which existed. Stat could not
execute a report, and report SQL is not valid T-SQL to begin with.

App\Support\SqlServer\BatchQuery runs the multi-statement batches the reports
are written as. Measuring it rather than reasoning about it corrected what an
earlier commit message here claimed:

- DECLARE and SET produce no result and were never the problem. The DML is: an
  INSERT reports an "N rows affected" result and fetching that fails with "the
  active result for the query contains no fields".
- Connection::selectResultSets() is not a fix. It walks the batch but calls
  fetchAll() on every result including the counts, so it fails identically.
- SET NOCOUNT ON works only if it is not sent as a prepared statement.
  Connection::statement() prepares, and with this driver a SET inside a
  prepared statement never reaches the session — @@OPTIONS & 512 stays 0.
  That is why adding it to the harness earlier appeared to do nothing. It has
  to go through unprepared().

Both measures now apply: counts suppressed for the session, and results with no
columns stepped over so a batch still runs where that did not take effect.
Stat and the test harness share this one implementation rather than keeping
parallel copies that could drift, which also means the harness tests now
exercise the production path.

App\Services\Analytics\CrystalParameters translates Crystal's {?Param} syntax
to bindings. Three forms, all replaced in a single left-to-right pass so values
land on the markers they belong to; one pass per form would group the bindings
while the markers stayed in document order and silently bind everything to the
wrong place. A quoted '{?StartBilling}' has the whole literal replaced, since
leaving '?' binds nothing and filters on a question mark — 43 reports use that
one form.

Sweeping the corpus caught a bug worth the exercise: several reports carry
commented-out parameter lines, and the driver ignores a ? in a comment.
Substituting there appends bindings for markers the server never sees, and
surplus bindings are taken from the front, so every real parameter shifts by
one — a report that runs and returns a plausible wrong answer. It is now a
scanner that skips comments, nested block comments and string literals.

All 118 kept reports that carry SQL translate with bindings aligned to their
live markers. Missing or unusable parameters raise rather than binding NULL,
because a NULL comparison is never true and the report would come back
confidently empty.

Full suite: 1307 passed, 10 skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The metric layer, and the first two reports on it. A report's SQL is a file
under resources/analytics/reports/, transcribed from the Amtelco doc with
Crystal's placeholders intact, so the query we run can be diffed against the
report it came from. genesis-service-level-data departs from its source in
exactly two places, both renaming a duplicated output column so a row can be
read by name at all; genesis-traffic is byte-identical. Both file headers list
the quirks they reproduce rather than fix.

MetricRegistry is the one dictionary: 36 metrics across the two reports, each
naming the report it came from and carrying a caveat where a reader needs one.
Building and running are separate, so parameter handling is unit-testable.
ReportingConnection resolves the handle and takes its own connection name
rather than the shared `intelligent` one, which is a placeholder with null
credentials that a dozen components overwrite during a request — sharing it
would let one of them swap the handle under a running report.

Two invariants are asserted rather than trusted, because both failure modes
produce a plausible wrong figure: declared parameters must match the SQL's
placeholders, and every metric must name a column its report actually emits.
Unknown parameter names are rejected, since a misspelling silently dropped
runs the report on a default, and QuickCallMax defaulting to 0 turns every
service level into a meaningless 100%.

Reading the full 278 lines rather than grepping for expressions corrected
three things this dictionary previously got wrong:

- Ring Call opens `CASE WHEN CE.selTalk > 0 THEN 1 ELSE ...`. The earlier
  entry quoted from the second line and so inverted the meaning: @RingMin
  drops short UNANSWERED calls only, and no answered call is ever filtered
  however briefly it rang. The test asserting otherwise passed because it
  encoded the same misreading.
- The abandons ARE gated by @RingMin. The comment "abandon flags without the
  RingMin filter" describes the innermost flag; the middle select wraps both
  and the outer select sums those.
- genesis-traffic returns one result set, not two. The second SELECT is the
  other arm of a UNION.

A fourth rule now heads the dictionary saying plainly that a grep is not a
reading, since two of those came from exactly that.

New finding, and the one most likely to be argued about: Announce calls count
as Answered — that expression has no Kind test — but every answer time comes
from a subquery filtered on `callType IN (1,2)`, so they can never have one.
They sit in the denominator of every answer time and every service level
contributing nothing to the numerator, so a site with much Announce traffic
reads materially worse than its agents achieved.

CrossReportConsistencyTest runs both reports over identical rows and pins
where they disagree: they count abandons differently (traffic's condition is
an OR, so it includes what the other calls Disconnected), mean different
things by "time to answer" (duration columns versus a timestamp difference),
and do not select the same calls for the same dates (traffic matches on
either stamp, service level on the end stamp alone).

Full suite: 1351 passed, 10 skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Amtelco's Answered has no Kind test, so an Announce call an agent spoke on
counts; but every answer time comes from a subquery filtered
`callType IN (1,2)`, so it can never have one. It lands in the denominator of
every answer time and every service level contributing nothing to the
numerator, and a site with much Announce traffic reads materially worse than
its agents achieved.

Reports\CallTheory\AnswerTimeExcludingAnnounce divides by live answered calls
instead. It does not replace Amtelco's figure, which is what a customer sees in
Crystal and the one that has to survive comparison with it: both come back in
the same row, plus [Answered Announce] so the gap is explainable in a sentence
rather than merely smaller. Every metric is flagged callTheoryMetric so it
cannot be displayed as Amtelco's.

It differs from genesis-service-level-data in exactly one respect. Everything
else is lifted verbatim, down to the redundant arithmetic in the
negative-wait-time fix, because a metric differing in two respects leaves
nobody able to say which one moved a number — the position the previous
attempt was in. That is asserted rather than claimed: the test runs the real
report over the same rows and compares the recomputed columns digit for digit.
With no Announce traffic the two figures are identical, so it costs nothing to
show on a site that never uses Announce.

MetricDefinition now separates attribution from emission. sourceReport is whose
arithmetic a figure is; emittedBy is which Report produces the column. They are
the same for almost every metric, and differ for the three comparison columns
here: the column is ours, the definition is Amtelco's and is credited to them.
Conflating the two had the column-existence check looking for our columns in
Amtelco's report.

Decisions applied:

- Sys SL % is the headline service level, being the only one of Amtelco's three
  with unanswered calls in the denominator and so the only one comparable with
  an external 80/20 target. Carried as MetricDefinition::$headline and held by
  a test, so the first screen cannot quietly pick another. The other two stay
  shown and labelled; writing that test found QuickCallAssigned % had no
  caveat, which for one of three confusable service levels it needs.
- Occupancy is measured against logged-in time, not scheduled hours.
- Billing totals are always computed in the switch timezone, and the period is
  labelled with that zone wherever a total appears.
- On-call becomes its own area holding the six metric reports; assignments,
  unassigned-shifts and unassigned-shift-reminder-emails stay under
  configuration, so the metrics-versus-setup split is preserved rather than
  excepted. Client and account reporting drops to 29 of 119.

Also settled the occupancy source by reading the corpus:
genesis-agent-work-time-summary carries no login data at all despite its name,
being entirely call-derived; statOpInterval is the source. Two things about it
cannot be answered from the corpus and are recorded with the query that
settles them — loggedIn's unit is never revealed because Amtelco only ever uses
it as a ratio denominator where it cancels, and Agt Time is in seconds, so a
tick count would be wrong by seven orders of magnitude; and reports disagree on
whether to MAX or SUM it across an agent's sessions.

Full suite: 1363 passed, 10 skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The answer was in the corpus, so no outside input was needed after all.

overview-reports-documentation.md is a report whose only output is Amtelco
documenting their metric names in prose, about sixty of them. It was absent
from amtelco-report-candidates.md entirely and so was never reviewed; found by
searching every doc for arithmetic on loggedIn rather than only the kept ones.

It settles the occupancy denominator by defining both metrics:
  Occupancy %   = agent call time / READY time
  Utilization % = agent call time / LOGGED IN time
So the logged-in ratio is their Utilization %, and ships under that name --
calling it "occupancy" would collide with their own vocabulary. The source is
statOpInterval; genesis-agent-work-time-summary carries no login data at all
despite the name, being entirely call-derived.

loggedIn is in seconds, by inference rather than statement: [Agt Call Time] is
SUM(Duration/10000/1000), i.e. seconds, and Utilization % divides one by the
other to get a percentage, so a tick count would read 0.00001%. Recorded as an
inference. It blocks nothing, because every one of these metrics is a ratio in
which the unit cancels; it matters only to display logged-in time as a
duration.

Amtelco also states a hard limitation on loginDur, readyDur, notReadyDur,
notReadies and Reassigns: "for the interval report the number is for all agents
logged in, there is no way to associate intervals with login data". Per-agent
utilisation at interval grain is not derivable. Their own reports disagree on
whether to MAX or SUM these columns, so there is no convention to adopt.

Two entries in that file bear on decisions already taken, and both are
recorded rather than acted on unilaterally:

- Amtelco annotates QuickCallAssigned % as "[Service Level]" -- their own
  label, on the assigned denominator, not on Sys SL %. The headline choice is
  therefore between what Amtelco calls service level and what the industry
  means, which are now known to be different columns.
- "An Announce call count. These are not distributed to an agent" materially
  weakens the premise of the Announce restatement. If such a call never reaches
  an agent it can never have selTalk > 0, so it never satisfies Answered and
  never enters the denominator; no report pairs Kind = 9 with selTalk. The
  dilution is structurally possible but probably never realised, and the
  earlier write-up overstated it. The metric stays -- it is cheap and
  self-diagnosing, reading identically when [Answered Announce] is 0 -- but it
  is a guard against what the SQL permits, not a correction of something known
  to happen.

Also confirms Avg RingDuration is a defect rather than a choice: the prose says
"divided by a count of calls with ring time" while the SQL divides by a count of
every row. Where prose and SQL disagree the SQL is what produced the number, so
the prose is treated as intent throughout.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four more Amtelco reports transcribed verbatim and registered, taking the
total to six plus one Call Theory report and 73 metrics: genesis-peak-traffic,
genesis-call-count-interval, genesis-abandontype and
genesis-call-completion-summary.

THE SCOPE ERROR, stated plainly because it cost real effort in the wrong
place. genesis-service-level-data and genesis-call-completion-summary were
both struck out in the candidates review (lines 118 and 79) and should not
have been surfaced. The service level report actually kept for the managers
area is genesis-service-level-interval-overview-5.4, which is not built --
and which is the one whose Assigned uses Kind NOT IN (3,9), the very
divergence the dictionary records against the report built instead. The cause
was working from the "Source reports" lists in analytics-suite.md, which were
guesses from filenames that the spec itself flagged as most likely wrong,
rather than from the reviewed list. The spec now says so, and says the
reviewed list is authoritative. Both reports stay registered for now because
each has reference value independent of being surfaced: the completion summary
is the only source of the completion-code enumeration, and the service level
report is the dictionary's entire citation spine.

CompCode is settled and needed no outside input: Amtelco enumerate it in a
comment at the head of several reports and map all five codes in
genesis-call-completion-summary. App\Enums\CallCompletionCode carries them,
with a test asserting the enum and the report agree. Park Abandon turns out
not to be an abandon in any figure, and the three codes that are neither
answered nor abandoned are why Offered Calls is lower than the call count --
demonstrated rather than asserted.

Both service levels are now surfaced, per the decision to show the pair:
Amtelco's own designated one (their documentation annotates QuickCallAssigned %
as "[Service Level]") and a Call Theory metric dividing quick calls by offered,
which is the conventional 80/20 basis none of their three columns uses. One
headline per attribution, held by a test. Sys SL % steps down to an ordinary
labelled metric, since it was only ever my approximation of the industry figure
and that figure can now be computed exactly.

Parameter defaults chosen, since Amtelco document none: QuickCallMax 12 (their
own commented test value in two reports), RingMin 0 (disabled, because a
non-zero floor silently excludes traffic and which calls it excludes differs
between reports), Opt 0 (the stricter reading, so it cannot flatter).

Supporting work:

- MetricDerivation lets a metric be defined as a ratio of two columns the
  report already returns, so the industry service level did not require
  transcribing a 278-line report a third time. Deliberately not an expression
  language: anything needing real arithmetic belongs in SQL where it can be
  diffed against its source.
- AllReportsExecuteTest runs every registered report and asserts it executes,
  that every metric names a column it returns, and that it runs from its
  declared defaults. One test over all reports, so adding a report puts it in
  scope rather than needing a new test to be remembered.
- TranscriptionFidelityTest compares each transcription against its source doc
  line by line, allowing only the departures each file header declares. The
  corpus is not mounted in the Sail container, so it skips there and must be
  run on the host; it touches no database.
- CommonParameters holds the date, client and billing ranges the reports share,
  so they cannot drift apart.

New divergences recorded: peak traffic requires completion code 0 to call a
call answered; the completion summary's ring filter uses >= with no answered
guard and so does drop short answered calls, unlike the service level report's;
and genesis-abandontype filters its date range in the CLIENT's timezone, so the
same dates select a different set of calls than every other report.

Full suite: 1391 passed, 16 skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The strike-outs were deliberate, so genesis-service-level-data and
genesis-call-completion-summary are no longer offered to a user:
Report::surfaced() returns false for both, and MetricRegistry gains
surfacedReports()/surfacedMetrics() which is what anything user-facing must
read. They stay registered because what depends on them would otherwise be
unverifiable -- the completion summary is the only source of the completion-code
enumeration, and the service level report is the citation spine of the whole
metric dictionary -- so deleting them would remove the proof while leaving the
claims. 5 of 7 reports and 36 of 73 metrics are surfaced.

A real defect in the translator, found while cataloguing the corpus's
parameters. A placeholder inside a string literal with other text around it --
`'%{?Search}%'`, which 17 reports use for LIKE patterns -- was left entirely
alone, because the scanner skipped literals wholesale. The parameter was
therefore silently inert: never bound, never reported by names(), so a screen
would not even have offered the input. Not a wrong answer, but a filter that
quietly does nothing.

Now a literal containing a placeholder becomes one binding with the value
interpolated inside it, so `'%{?Search}%'` binds `%abc%` and keeps its
wildcards. That subsumes the old special case for `'{?Param}'`, which was the
same thing without surrounding text, so the two forms are one rule and the
pattern lost an alternative. Doubled quotes collapse to single ones in the
bound value, as SQL means them. A list inside a literal raises, since there is
no faithful substitution.

All 118 reports that carry SQL still translate with their bindings aligned to
their live markers.

While rewriting the tests for this I deleted two correct passing tests -- the
line-comment and nested-block-comment cases -- by replacing a wider region than
intended. Restored; the file is back to 19 tests. Also switched
TranscriptionFidelityTest to getenv, since env() returns null once the config is
cached.

Worth recording about static analysis: phpstan.neon.dist analyses app/ only, so
the clean results reported for tests/ in earlier commits were never in scope.
The configured run is 65 errors, all pre-existing in app/, none in this work.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
113 reports registered, 3,286 metrics. Every report kept in the candidates
review is now transcribed verbatim, registered, and proven to execute.

Writing a class per report would have been thousands of lines of near-identical
declaration, so the bulk are described as data in resources/analytics/reports.php
and instantiated through GeneratedReport. tools/scaffold-analytics-reports.php
builds that manifest from the corpus: it transcribes each report's SQL, works
out which snapshot tables it touches, creates them, runs it, and reads the real
column names off the statement -- necessary because 29 reports cannot be read
statically, 16 ending in SELECT * and 13 aliasing nothing detectable.

REVIEWED AND SCAFFOLDED ARE NOT THE SAME THING, and Report::reviewed() carries
the distinction. A reviewed report has a hand-written class with real caveats
naming where a figure is not what a reader would assume; seven are reviewed and
between them they turned up about a dozen material divergences. A scaffolded
report has verbatim SQL and metric formulas that are the verbatim SQL
EXPRESSIONS -- never invented prose, because a plausible description nobody
checked is exactly how the previous attempt produced figures nobody could
defend. What has not been done for those 106 is checking whether a column name
means there what it means elsewhere, which is the commonest way these figures
mislead. Every scaffolded metric says so, and one using a name from the
dictionary's conflict list says that too.

So "113 reports available" is true and "113 reports whose numbers have been
argued through" is not. The spec says so plainly.

Nine kept reports could not be built, each for a stated reason rather than a
shrug: three read tables absent from the schema snapshot (mOnCallAlert,
mOnCallDetails, mClientMaint); four return a duplicated column name from a join
with no AS to rename, which no generator should silently paper over since a row
read by name returns only one of the pair and leaves the other reading as null;
one names a second database the test server lacks; one has no SQL at all.

Supporting work:

- ReportParameterCatalogue holds all 48 Crystal parameters with types DERIVED
  from the reports' own DECLARE statements, not guessed from names -- each
  `SET @Var = {?Param}` traced back to its declaration. Twelve of them only
  became visible once the translator started handling placeholders inside
  string literals.
- BatchQuery::columnNames reads a batch's column shape without fetching rows,
  which is what lets all 113 reports be column-checked with no seed data.
- IntelligentTestSchema gains tables() and tablesFor(), the latter resolving a
  dbo. or [dbo]. prefix -- missing that cost a scaffolding run, with eight
  reports failing on "Invalid object name 'dbo.agtAgents'".
- MetricRegistry resolves the manifest from __DIR__ rather than resource_path,
  so it works unbooted. PHPUnit calls static data providers before the
  container exists, and a provider that throws there yields no tests at all
  rather than a failure anybody notices -- which is what happened.

Two bugs in the generator, both found by its own failures and both of the kind
that would have shipped quietly. Renaming duplicated output aliases was
matching every AS in the file, including inner scopes that the outer query then
referenced, breaking eight reports with "Invalid column name 'agtName'"; it now
rewrites only inside the outermost SELECT list. And a metric key slug dropped %
and #, so agent-ready-not-ready's "Ready" and "Ready %" collapsed to one key
and one became unreachable.

Integration suite: 283 passed. PHPStan unchanged at the pre-existing 65.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The previous commit was pushed before its full-suite run finished, and that
run came back with two failures. Both were wrong assertions of mine rather
than defects in the reports, but the commit was bad and this repairs it. The
ordering was the mistake: the suite should have gated the commit, not followed
it.

- "every report can build a query from its defaults" demanded that every
  report produce at least one binding. Several setup and snapshot reports take
  no parameters at all -- agents-active, genesis-acd-setup, clients-sources,
  unassigned-shifts and others are point-in-time dumps. The assertion that
  actually matters is that the binding count matches the marker count, which
  holds when both are zero.
- The metric key pattern forbade a leading digit in the metric half, but
  genesis-live-calls-minutes returns columns named "1 Minute", "2 Minute" and
  "3 Minute". Those are duration buckets and perfectly reasonable names; the
  pattern was wrong, not the data. The area half still may not start with a
  digit, since it comes from a report key.

A third thing surfaced and is correct behaviour rather than a bug: a report
with a required multi-value parameter cannot be run from defaults, because the
parameter expands to an IN list and `IN ()` is not valid SQL. So a screen has
to insist on that input. Tests\Support\ReportFixtures now holds the one
definition of "what would a screen send", shared by the unit test that builds
every report's query and the integration test that executes every one, because
two copies would drift and the tests would then be checking different things.

Full suite: 1598 passed, 122 skipped. The skips are the 112 transcription
fidelity cases, which need the report corpus and so cannot run inside the Sail
container, plus 10 pre-existing. PHPStan unchanged at 65, none in analytics.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
oncall-alerts, oncall-details and client-maintenance are struck from the
candidates list. They are Infinity reports, not Genesis: each description opens
"The MDR – ... report is available with Amtelco's Infinity automated call
distribution system", and each reads m* tables -- mOnCallAlert,
mOnCallDetails, mClientMaint -- that are absent from the Genesis schema
snapshot.

So the reason is better than the one recorded before. These were not a gap in
our snapshot; they were out of scope from the start, the module being
Genesis-only by decision. The original classification missed them because it
keyed on which stat*/m* tables a report's SQL touched and these names did not
match its pattern. Two independent signals agree -- the descriptions and the
failure to build -- and a sweep confirms no other kept report carries the
Infinity marker.

Kept reports: 116. Reports that could not be built: 6, down from 9. The on-call
area drops from six reports to four, which is small enough to reconsider
folding back into client reporting, though the audience argument still holds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A library of 113 reports nobody can view is not a feature. Two pages, gated on
utility.analytics in the controller rather than the component, because Livewire
swallows an abort() raised in mount() on a full-page render.

/utilities/analytics lists every surfaced report grouped by area, searchable by
title, key or metric label, filterable by area. /utilities/analytics/{report}
runs one: parameter form prefilled from the declared defaults, then charts, the
numbers, and the definition behind every column.

Four decisions in there that are not defaults:

- Nothing runs on load. statCallTracker alone is 27 million rows, so a page
  that queried on render would make opening the library expensive and do it
  again on every Livewire round trip. The reader sets parameters and asks.
- Every column is shown with its provenance -- the Amtelco report it came from,
  its formula, its caveat. The previous analytics area was deleted because
  nobody could say where its numbers came from.
- A failure is shown, not swallowed. An empty table and a query that fell over
  look identical otherwise, and the first is a fact about the business while the
  second is a bug.
- The library states which reports are reviewed. Hiding the difference between
  "accurate about its own SQL" and "checked against the rest of the corpus"
  would be the most misleading thing either page could do.

CHARTING. ChartPlanner reads the grain and the rows actually returned:

- The grain picks the form. Interval and day data is a line, skill/agent/client
  is bars, and per-call data is NOT charted -- three thousand calls plotted is a
  solid block that looks like information and is not.
- Measures of different units never share an axis. A service level of 28.6%
  beside a count of 12,431 makes the percentage invisible, and a second y-axis
  is worse: it lets whoever drew it imply any correlation by choosing the
  scales. Units split into separate charts, asserted by test.
- Eight series maximum, coloured in fixed order, never cycled. Overflow becomes
  another chart rather than a ninth hue, because two series the same colour is
  worse than two charts.
- A percentage axis is pinned to 0-100, so a two-point spread does not look
  like a cliff.

The palette was validated, not chosen by eye: --color-chart-1..8 in both the
@theme and .dark blocks pass the lightness band, chroma floor, CVD separation,
normal-vision floor and contrast against each mode's own surface. The ORDER is
part of what passed, since the checks are on adjacent pairs. Dark mode is
selected rather than flipped -- the band is the same in both modes, so the
400-level ramp fails it. The worst adjacent pair sits at tritan 7.1, inside the
6-8 floor band, which is legal only alongside secondary encoding; hence a legend
at two or more series, direct labels at four or fewer, 2px surface gaps, and the
table view. The table is not a fallback.

Colours leave the server as token NAMES and are resolved in the browser from the
live stylesheet, so a chart repaints on a theme toggle and app.css stays the one
definition. Hex in the payload would wear light-mode colours on a dark surface
forever. ECharts is imported dynamically only when a chart is on the page: it
builds to a separate 1.1MB chunk and app.js stays at 170KB.

Analytics is not an open utility -- admin, manager and supervisor only. A team
without it enabled gets 404 rather than 403, which is the house rule and the
right one: a 403 would confirm the feature exists to a team that has not bought
it.

Host suite: 1338 passed, 409 skipped. PHPStan back at the pre-existing 65.

The 409 skips are the SQL Server integration tests. Docker stopped partway
through this work and cannot be restarted from here without root, so the new
end-to-end viewer test -- which drives the real connection resolution, presses
Run and asserts on the rows and charts -- has not yet been executed. It needs
`sail up -d mssql`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Analytics did not appear anywhere, and navigation was not the reason -- the
utilities-grid card and dropdown entry were both there, gated on @can. Three
gates sat behind them and two were broken.

THE SYSTEM SWITCH DID NOT EXIST. System -> Enabled Utilities was a hand-written
block per utility: a public bool, a toggleXUtility() method, and a hardcoded
Blade row. Adding a case to the enum produced a capability, a team column,
routes and pages, and no switch -- so the flag could never be set and the @can
never passed. Nothing failed; the utility simply was not there.

MCP Server had been in the same hole since it shipped. mount() listed 14 of 16
utilities, so its flag could only be set by editing a flag file by hand, which
is why its own test calls enableSystemFeature() directly rather than using the
page.

The page now iterates App\Enums\Utility, as Teams\EnabledUtilities already did
-- that component's comment says a new utility appears "the moment it is added
there", which was true of the team page and not of this one. One
toggle(string $utility), resolved through Utility::tryFrom as an allow-list so a
value from the browser cannot name a flag file. Both missing utilities are fixed
by the same change and the next one needs no edit here.

THE CAPABILITY REACHED NEW TEAMS ONLY. config/roles.php is a template applied
when a team's roles are created, and SeedDefaultRolesForTeam deliberately syncs
capabilities only for roles it creates, so it never touches an existing one --
otherwise it would clobber an admin's edits on every run. Adding
utility.analytics there granted it to new teams and left every existing install
on a 403. A migration grants it to existing admin, manager and supervisor
roles, in the same shape as 2026_09_03_000002, which hit this for
system.observability.

The team-level toggle was already fine, since that page iterates the enum.

Eight new tests assert over Utility::cases() rather than about Analytics: every
utility has a switch wired to its own value, a tracked switch state, a team
column, a capability, and that capability actually granted to a seeded admin.
Analytics specifically is granted to manager and supervisor and withheld from
agent. An unknown value passed to toggle() 404s. The next utility cannot
silently fail to appear.

To see it on an existing install: php artisan migrate, then enable Analytics at
System -> Utilities and for the team at Teams -> Utilities.

357 system and utility tests pass. PHPStan unchanged at the pre-existing 65.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Analytics shipped as a utility: a system feature flag, a `utility_analytics`
column, a tile on the utilities grid, and an administrator switching it on team
by team. That was the wrong shape. A utility is something a team opts into.
Analytics is part of the application -- it belongs in the top navigation beside
Dashboard and Accounts, on for every team, with the role deciding who may open
it and the team's own allowances deciding what they are told.

So the flag and the column are gone, `utility.analytics` becomes `analytics.view`
beside `accounts.view`, and the pages move out from under /utilities:

  /utilities/analytics           -> /analytics
  /utilities/analytics/{report}  -> /analytics/{report}

with the controller, the Livewire components and their views following the URL
out of the Utilities namespace. The nav entry renders in both the desktop strip
and the responsive menu -- a nav item invisible on a phone is half-built.

The gate is now the capability alone, which means 403 and not the 404 a disabled
utility returns. That is the right answer here: the 404 exists to avoid
confirming a feature a team has not bought, and every team has this one.

Two things the utility flags used to carry for free had to be restated:

`Capability::requiresRealTeam()` refuses a personal team. A personal team has no
account scoping, so there would be nothing to narrow a report to, and a global
suffix rule can otherwise grant a capability on whatever team is current.

`App\Support\AnalyticsScope` answers the harder half. Every report here is
whole-operation -- Amtelco's SQL counts every call on the switch -- and nothing
yet narrows a result to a team's accounts. While an administrator had to enable
the utility per team that stayed theoretical; on by default it does not. A team
whose account scope has never been decided cannot run a report, which is the
rule CallAccess already applies to the call log. A team restricted to an account
list is told on the page that the figures are not narrowed to it, rather than
refused: whether an operation-wide number is acceptable for an internal team is
theirs to decide, but quietly overruling their allow list is not.

Both components also gained the capability themselves via
AuthorizesSystemComponent. They had none -- the page controller was the only
gate, and Livewire does not re-run it on POST /livewire/update, so a reader whose
capability was revoked mid-session could keep pressing Run.

The two migrations this replaces added the column and granted the old
capability. They were never released but were on this branch long enough to have
been run, so both halves are undone conditionally and an existing grant is
carried across rather than dropped -- a role an admin had already edited keeps
analytics.

1353 tests pass; PHPStan unchanged at its 66.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
A fresh database migrates straight to the end state, so the conditional cleanup
in 2026_10_11_000001 does nothing and nothing in the suite reaches it. The only
machines where it does something are the ones that ran the two superseded
migrations while they were on this branch -- which is the case it exists for.

So the intermediate state is rebuilt by hand and the migration run against it.
The part worth pinning is that an existing grant is carried rather than
re-seeded: the test gives the capability to dispatcher, which the template never
grants, and asserts dispatcher still holds it afterwards. A role an admin had
already edited has to keep analytics, and SeedDefaultRolesForTeam will not put it
back -- it only syncs capabilities for roles it creates.

1355 tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Uploading a TBS export appeared to work -- a file with a generated name turned
up on disk -- and then no row was ever imported, with nothing in the browser
console and nothing in GlitchTip.

Filament's FileUpload stores the upload during form submission and leaves a path
string in the action's data, so by the time the action body ran,
`$data['tbsExportFile']` was `01K7ABC....csv` rather than the uploaded file.
save() re-validated it with the `file` rule, which a string fails, and the
ValidationException went into an error bag nothing on this page renders -- the
modal had already closed. The import stopped there. Nothing reached GlitchTip
because a ValidationException is a handled exception and is not reported, which
is why this looked like a silent crash rather than the validation failure it was.

A regression from 6c347c8, the Filament lift and shift: the bare
<input type="file"> it replaced handed save() a real uploaded file. Nothing
caught it because every existing test sets `records` directly, so the one step a
user actually performs had no coverage.

`storeFiles(false)` keeps the upload as the uploaded file and leaves storing to
save(), where it was. That also keeps the destination server-side: Filament's
stored path is submitted by the browser on the next request and
preventFilePathTampering() is off by default, so with no record to check a path
against, a crafted payload could have pointed `tbsExportFile` at any file under
storage/app and had columns 25-32 of it parsed back out.

Two further faults found in the same workflow:

clearSession() called session()->flush(), which empties the whole session
including the authentication state -- clearing an import signed the user out on
their next request. It now forgets only the five keys this page owns.

Line 0 is read as the column labels and the parse loop then walked every line
including line 0. In the exports this was written against the header row is
narrower than a data row -- hence labels at columns 17-24 against data at 25-32
-- so it fell under the 38-column test by coincidence of shape rather than by
anything enforcing it. A report whose header spanned the full width would have
arrived as a row to charge. Line 0 is now skipped explicitly.

Also added: a warning when a file parses to zero rows. Rows are read by column
position, so a report rebuilt at a different width yields an empty table, which
reads as "no balances to bill" -- the most expensive available misreading.

Ten tests over the upload path. Reverting both fixes fails nine of them. The
Stripe charge path is still uncovered; it is not reachable from a test here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Three Forgejo Actions jobs on every pull request and every push to main, kept
separate so a red build says which thing broke: the suite, static analysis
(pint --test plus phpstan), and whether the assets still compile.

Every job runs inside a prebuilt PHP 8.4 container rather than installing PHP on
the runner. This suite needs ext-mailparse, which is in no stock PHP image, and
the integration tests need sqlsrv and pdo_sqlsrv, which exist only as pecl
builds; both compile in minutes, which would cost more per run than the tests do.
docker/8.4/Dockerfile already installs all of it, so CI runs the environment
developers already use.

The image is not hardcoded. A repository variable CI_IMAGE overrides it for every
job, and a fork that sets nothing falls back to the published literal -- which is
why that image wants to live in a public registry project. Nobody should need our
credentials to run the tests they inherited. docs/development/ci.md covers
building and hosting your own.

Two constraints shaped the file and are worth knowing before editing it. The tag
appears three times, once per job, because `container.image` is evaluated before
a job's environment exists -- no workflow `env` and no earlier step can supply it.
And a private registry cannot be authenticated from the workflow at all, because
the job container is pulled before any step runs, so `docker login` is too late;
that belongs in the runner's own Docker config.

A fresh clone could not run the tests
--------------------------------------

tests/TestCase.php now calls withoutVite(). layouts/app.blade.php calls @vite()
and public/build is gitignored, so `composer install && php artisan test` on a
clean checkout threw ViteManifestNotFoundException from every test that renders a
page. The suite passed locally only because developers had run `pnpm run build`
at some point. Verified both directions by moving public/build aside: six of the
seven tests in UtilitiesEmptyStateTest failed before, and the full suite passes
after -- 1268 tests with no built assets present.

Nothing in the suite asserts on asset URLs. Whether the assets compile is a real
question, so it gets its own job rather than being smuggled in as a side effect
of every other test.

Also removed the root Dockerfile: a four-line PhpStorm stub -- `FROM
ubuntu:latest` with `ENTRYPOINT ["top", "-b"]` -- that builds nothing and is not
referenced by docker-compose.yml, which points at docker/8.4/Dockerfile. It
would eventually have been mistaken for a deployment artifact.

The Integration testsuite is deliberately not wired up here. It is introduced by
the analytics branch, and declaring a SQL Server service for a suite that does
not yet exist would spin up a gigabyte of database to do nothing on every push.
The job is written out in docs/development/ci.md, to be added by the change that
adds the suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
The first run never reached a step:

  docker pull image=harbor.calltheory.com/mission-control/ci:8.4-1
  Error response from daemon: Get "https://harbor.calltheory.com/v2/":
  dial tcp: lookup harbor.calltheory.com: no such host

My invention, from the registry being Harbor rather than from anything that
resolves. The host is cr.calltheory.com. Corrected in all four places -- three
job definitions and the integration-suite example in the docs.

Confirmed against the registry rather than assumed this time:
cr.calltheory.com resolves, the repository path mission-control/ci exists, tag
8.4-1 is present, and an anonymous bearer token is granted for
repository:mission-control/ci:pull -- so the fallback image pulls with no
credentials. That is what the docs promise a fork, and it is now a checked claim
instead of a hopeful one.

No PHP changed, so the suite is unaffected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
The asset build failed to resolve the first line of real work:

  [@tailwindcss/vite:generate:build] Can't resolve
  '../../vendor/filament/support/resources/css/index.css'
  in '/workspace/calltheory/mission-control/resources/css'

resources/css/app.css imports seven stylesheets out of vendor/filament and
@sources Filament's PHP and Blade so Tailwind can scan them for class names. So
the asset build depends on Composer packages, not only node ones -- a coupling
between the PHP and front-end dependency trees that is invisible from
package.json. I gave that job pnpm alone.

Added the same Composer cache and install the other two jobs use, with
--no-scripts: nothing here boots the application, it only needs the files on
disk.

Worth stating the stronger version in the docs, which it now says: a build that
resolved the import but ran without vendor/ would still succeed and emit CSS
missing every Filament class. The failure is loud; the near-miss would not be.

This is the kind of thing only CI finds. Locally vendor/ is always present, so
`pnpm run build` passes on a developer machine whatever the job does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
It failed, and would have failed a second time after the obvious fix, because
both halves of it were wrong.

Pint
----

`vendor/bin/pint --test` with no arguments reports 60 style issues across 825
files. The codebase was never uniformly Pint-clean, and none of those files are
anyone's current work. Reformatting them wholesale would produce an unreviewable
diff claiming authorship of churn nobody intended -- which has happened in this
repository before.

So the job now runs `pint --test --diff=origin/main`: only what the branch
changed. New code is held to the standard, old drift stays its own deliberate
pass. That needs `fetch-depth: 0` and an explicit fetch of main, because
actions/checkout fetches the pull request's head and not the branch it targets,
leaving no merge base to diff against.

PHPStan
-------

`phpstan analyse` exits non-zero whenever it finds anything, so the job would
have failed on 66 pre-existing errors. I wrote in the workflow that the codebase
"carries a baseline" and that the count "cannot grow without someone noticing" --
neither was true. There was no baseline; there was me remembering a number
between runs.

There is one now. phpstan-baseline.neon records the pre-existing errors, so a
clean run exits zero and only a new error fails the build.

Generating it turned up something: of the 66, only 60 were findings. The other
six were `ignoreErrors` entries PHPStan reports as never matching -- stale
decisions whose errors had stopped being produced at some earlier point. The
number I had been tracking all along was six higher than the real one. Those six
are removed rather than silenced with reportUnmatchedIgnoredErrors, so the next
one to go stale is still reported, and the comment block left with no entries
under it is gone.

Worth keeping the two mechanisms distinct, which the docs now do. The
hand-written ignoreErrors list is decisions, each with a comment saying why
PHPStan is wrong about that code; it is meant to be read. The baseline is a
machine-written list of what nobody has got to yet, and entries come out as the
code is fixed.

No PHP changed. phpstan analyse: no errors. pint --test --diff=main: passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Two tests failed in CI and pass everywhere else:

  LocalSpoolFilesystemTest > it reports an unwritable source
  Failed asserting that true is false.

  LocalSpoolFilesystemTest > it surfaces a write failure
  Failed asserting that exception of type SpoolUnavailable is thrown.

Both chmod a directory to 0555 and expect a write to be refused. CI runs as
root, and root bypasses the permission check, so 0555 means nothing to it: the
directory is still writable, the probe reports writable, the write succeeds, and
both assertions invert. I wrote the fact that these jobs run as root into
docs/development/ci.md two commits ago and did not connect it to this.

They now assert the precondition instead of assuming it -- chmod, then check the
directory really is unwritable -- and skip with the effective uid named when it
is not. Asserted rather than inferred from the user id, so an ACL or a mount
option producing the same result is covered for the same reason.

posix_geteuid(), not getmyuid(): the latter reports the owner of the script file
rather than who is running it, and those differ in exactly the case the message
is about -- root executing a workspace owned by someone else.

Also added clearstatcache() before the check, since chmod() does not invalidate
the stat cache and a prior stat of the path would otherwise be answered from
before the change.

What this costs is in the docs rather than left for someone to discover: on CI
as it stands, nothing checks that an unwritable spool is reported rather than
silently accepted. A green run is not evidence for it; running the suite as a
normal user is. Making CI cover it means running the job as non-root, which
means dealing with workspace and cache ownership.

14 tests in that file pass locally, none skipped at uid 1000.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
PHPUnit 12 removed support for the `/** @test */` doc-comment annotation. Seven
files in tests/Feature/Console/Commands relied on it exclusively -- not one of
their methods carried a `test` prefix -- so PHPUnit saw seven empty classes:

  No tests found in class "Tests\Feature\Console\Commands\SyncISDataTest".

That is a test-runner warning, which makes TestResult::wasSuccessful() false and
exits 1. Collision's summary renders passed/failed/skipped and not warnings, so
every run printed a clean "1268 passed" while returning failure, and the JUnit
log agreed because the missing tests were never collected to have an outcome.
Twenty test methods had not run for as long as this repository has been on
PHPUnit 12. Nothing on a developer machine would ever have said so; CI found it
on its first green-looking run.

Renaming them to the house `test_` prefix made them run, and thirteen failed.
None of the failures were what the error text first suggested.

Six were a stale API: Helpers::enableSystemFeature() does not exist, and the
suite drives flags through the InteractsWithFeatureFlags trait. Switched.

Ten `->expectsOutput('')` calls across four files assert that a literal empty
line was printed. No command here prints one and no author can have meant it --
the files that pass assert real text, like 'Checking recording wav files...'.
Removed the incoherent line; every real assertion stays.

PurgeBoardCheckActivityTest needed a factory, written from the `activities`
migration, and also asserted against a `board_check_activities` table that is
never created: the model declares no $table, so Eloquent resolves Activity to
`activities`. Those assertions would have thrown even with the factory.

SyncISDataTest asserts that SyncMergeCommWebHooks is dispatched. In
SyncISData::handle() that dispatch is commented out, and has been since before
the initial public commit, so the command is a no-op returning SUCCESS -- while
still being scheduled every thirty minutes in Kernel.php:77. Uncommenting it to
satisfy a test would be deciding that the sync should run, which is not a test's
call to make. The test now asserts what the command does and fails if the
dispatch comes back without the real assertion being restored.

ConvertRecordingTest's three were never valid rather than rotted. Redis::fake()
is not a Laravel feature: the facade forwards it to Redis as a command named
FAKE, and predis rejects it, which killed all three in setUp. Redis::assertExists()
and $this->assertDispatched() do not exist either. Past those, the command does
`new Call([...])` instead of resolving from the container, so $this->mock(Call::class)
cannot intercept it, and recordingData() queries Intelligent Series. Real coverage
needs SQL Server, Redis and sox, which makes it an integration test. Skipped with
the whole reason in the class docblock rather than deleted or faked green.

Net effect, measuring the exit code rather than a pipeline's last command:

  before   10 skipped, 1268 passed (3517 assertions)   exit 1
  after    13 skipped, 1285 passed (3589 assertions)   exit 0

Seventeen more tests and seventy-two more assertions actually running. PHPStan
unchanged.

Two things this turned up that are not test problems and are left alone:
intelligent-data:sync is scheduled every thirty minutes and does nothing, and
ConvertRecordingTest needs either a move to tests/Integration or a command that
resolves Call through the container.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
.pnpm-store/ held 1,984 committed files, 33.3 MB, all of it under v11/files as
hashed blobs. It is pnpm's cache, not source, and it arrived in 67fc47e
("updated components and interface for usability") alongside unrelated work.

Worth recording why it is there, because it is not a misconfiguration anyone can
simply avoid repeating: there is no .npmrc in the repository and no store-dir in
the user config, yet `pnpm store path` resolves to <repo>/.pnpm-store/v11. pnpm
relocates its store into the project when HOME is on a different filesystem,
which is routine under WSL2. So pnpm put a cache in the working tree and it got
committed. Ignoring it is what stops that recurring on the next machine with
that layout.

Removed from the index only -- the directory stays on disk, so local installs
keep their cache -- and added to .gitignore beside /node_modules, in the same
anchored style as the other entries.

This stops the growth; it does not shrink the repository. Those objects remain in
the pack, so clones still fetch them. Excising them means rewriting history,
which would change every commit hash from 67fc47e onward and invalidate 41 tags
and every existing clone. Not worth it for 33 MB, and certainly not worth
bundling with anything else.

Verified `pnpm run build` still succeeds afterwards: 64 modules, manifest and
bundles written as before.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Make the report manifest pint-clean, and keep it that way when regenerated
All checks were successful
CI / Asset build (pull_request) Successful in 58s
CI / Static analysis (pull_request) Successful in 1m37s
CI / Test suite (pull_request) Successful in 13m52s
c6e21c540a
CI's `pint --test` job would have failed this branch on two files I never
formatted: tools/scaffold-analytics-reports.php, which is hand-written and was
simply missed, and resources/analytics/reports.php, which is generated.

The generated one is the one that matters, because it regenerates. It is written
with var_export(), which emits array(...) and its own indentation, so formatting
it by hand once would leave the next person who runs the scaffolder with a red
build and no obvious cause. The generator now formats its own output.

It runs pint twice and then verifies with --test, which is not belt and braces:
a fixer's output can trigger another fixer, so one pass is not always enough,
and `pint` in fix mode exits 0 whether or not anything is left to do. The status
code therefore says nothing on its own. I found that out by reporting the
scaffolder "fixed" and having --test fail immediately afterwards.

main is merged in, so this branch carries the CI workflow, the test repair and
the PHPStan baseline. Against that: pint --test --diff=main passes, phpstan
reports no errors, and the suite is 1382 passed, 125 skipped, exit 0.

Worth saying plainly what those skips are, because a green run here will claim
more than it has earned: 104 of them are TranscriptionFidelityTest's data sets
and the rest of the analytics report tests, all of which need SQL Server. The
checks that every one of the 112 transcribed reports matches its Crystal source
and executes are exactly the ones that do not run without it. docs/development/
ci.md has the service-container job written out for this; this branch is the
concrete reason to add it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJ
Merge branch 'main' into feature/analytics-suite
All checks were successful
CI / Asset build (pull_request) Successful in 47s
CI / Static analysis (pull_request) Successful in 1m31s
CI / Test suite (pull_request) Successful in 13m47s
6e6439fcee
The first time the integration suite ever ran against SQL Server, 286 of 287
passed and this one failed:

  ReportViewerEndToEndTest > a report that matches nothing says so rather than
  showing an empty chart
  To contain: ran and matched nothing

The viewer was right; the test picked the wrong report. genesis-traffic builds an
@Intervals table with a WHILE loop and LEFT JOINs the calls onto it, so a window
with no calls in it still returns one zero-filled row per interval -- 24 rows of
zeros for a day at 60 minutes. By Amtelco's design it cannot come back empty, so
the empty-state block never rendered.

Switched to call-detail, which is one row per call with no interval spine, and
added agtAgents to the provisioned tables because call-detail joins it.

Against the containerised SQL Server: Integration 287 passed, exit 0. Separately,
TranscriptionFidelityTest on the host against the learn.calltheory.com corpus:
112 passed, exit 0. Between them that is the first execution of both halves of
the analytics verification -- every transcription matches its Amtelco source,
and every report runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019DLYxPYkMy1Ezbax3x4s2K
Merge remote-tracking branch 'live/feature/analytics-suite' into feature/analytics-suite
All checks were successful
CI / Asset build (pull_request) Successful in 41s
CI / Static analysis (pull_request) Successful in 1m33s
CI / Test suite (pull_request) Successful in 14m2s
25e0d834ee
Take the review labels off the analytics pages
All checks were successful
CI / Asset build (pull_request) Successful in 56s
CI / Static analysis (pull_request) Successful in 1m35s
CI / Test suite (pull_request) Successful in 13m58s
609abf2773
These are Amtelco's reports, run as Amtelco ships them. Stamping each one with
our own verdict on whether it had been "reviewed" was editorialising on every
page, and it is out:

  - the "Not yet reviewed" box on the report viewer;
  - the Reviewed / Not reviewed tag on every library card, and the header
    sentence that counted them;
  - the disclaimer prefixed to every column of all 106 scaffolded reports in the
    definitions table, some of which also pointed users at an internal developer
    document, docs/specs/reference/metric-dictionary.md.

The library header now reads simply that the reports run exactly as Amtelco
ships them and that every figure names the report it came from.

Kept: the caveats the five hand-written reports carry on their own metrics --
that Assigned and Abandoned are defined differently across reports, and how the
Call Theory answer-time figure departs from Amtelco's. Those are statements about
particular columns, not a blanket label, and MetricRegistryTest holds them.

The two page tests that asserted the labels were present now assert they are
absent, so they do not drift back in.

Report::reviewed() still exists internally; nothing user-facing reads it.

Unit+Feature 1382 passed, Integration 287 passed, both exit 0 in Sail;
TranscriptionFidelityTest 112 passed on the host against the corpus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019DLYxPYkMy1Ezbax3x4s2K
All checks were successful
CI / Asset build (pull_request) Successful in 56s
CI / Static analysis (pull_request) Successful in 1m35s
CI / Test suite (pull_request) Successful in 13m58s
This pull request has changes conflicting with the target branch.
  • .env.example
  • app/Console/Commands/ISFaxing/CheckPendingFaxes.php
  • app/Http/Controllers/API/Webhooks/FaxWebhookController.php
  • app/Livewire/Concerns/ShowsFaxFailures.php
  • resources/views/utilities/cloud-faxing/failures.blade.php
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 'feature/analytics-suite:feature/analytics-suite'
git switch 'feature/analytics-suite'
Sign in to join this conversation.
No reviewers
No labels
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
calltheory/mission-control!7
No description provided.