Research & Known Gaps

Research & Known Gaps

How we know what this guide claims, what is measurably true today, and — in the same amount of detail — what is not true yet. A reader who trusts the rest of this guide is entitled to know exactly where its ground stops.

How this guide was verified

Every behavioural claim in this guide was read out of the working tree, not recalled from a specification. Where the specification and the code disagreed, the code won and the specification was corrected — that happened at least four times (see Decisions). The files below are the primary sources.

The module itself

Outside the module

Milestone evidence

M1 — the dispatcher does not double-fire

Run against the dev primary database dev_app with a throwaway, self-cleaning harness. The point of M1 was never "it runs" — it was idempotency, because a scheduler that opens two runs for one occurrence would later approve the same record twice.

Tick 1 opened exactly one run, advanced next_run_at_utc, wrote the 64-char idempotency key, snapshotted the configuration and stamped a correlation id. Re-presenting the same occurrence on tick 2 created no second run. An unregistered type closed its run failed / DEFINITION_UNAVAILABLE and moved the automation to needs_review rather than retrying forever. Every test row was removed and the module toggle restored.

M2 — the inertness proof

Observe mode's entire value is that it changes nothing. "We looked and it seemed fine" is not evidence of that, so the M2 run on tenant dev_c_rs8 fingerprinted the database before and after:

Alongside that: 356 candidates evaluated, matching an independent SQL count exactly; every item carried an outcome and a reason code; the counts reconciled (would + skipped = candidates); Observe results landed in would_count and never in approved_count; exactly one audit row was written for the run. Test suites: 41 module / 230 HumanResource / 955 core. A browser pass over the UI scored 27/27 — one fragment fetched on load, unvisited tabs empty, tab switching not navigating, re-selection not refetching, both server-side DataTables initialising, no stuck-light panel in dark mode, zero JS errors.

M3 — the cap held, and the rollback was clean

The Live run was driven through the real cron CLI against real attendance on tenant dev_c_rs8. The headline number is the one to internalise:

Every one of the 25 came out status=approved, with checked_by set to the System actor, checked_at stamped, and carrying the attendance_metrics row payroll reads. Each per-record audit entry was remarked automation; the run recorded itself run_mode=live. No record outside the approved 25 changed. Rollback restored all 120 rows byte-identical, leaving zero system-actor approvals, zero leftover automations, zero orphan metrics rows and zero leftover audit rows. Clone was verified separately at 15/15 in the browser and 28/28 in the database, against a source deliberately left published, live, scheduled and on revision 7 with run pointers — every reset checked, the source itself unmodified.

The System actor was seeded on three databases and confirmed user_type=system, status=inactive, disable_login=1, and invisible to every staff-scoped query. Suites at M3: 968 core / 255 HumanResource / 61 Automations.

What is not shipped

Milestones 4 and 5 are pending in full. Nothing below exists in the working tree; do not design against it, and do not report its absence as a bug.

Two deliberate deferrals, distinct from "pending": the dashboard widget pair (config/widgets.php + helpers/automations_widget_helper.php) is a natural MINOR follow-up, and the automation_daily_metrics rollup table will be built only on a measured need — deriving from run aggregates satisfies the single-source-of-truth rule until a measurement says otherwise.

Phantom APIs — declared, documented, and read by nothing

This section is the one most likely to save you a wasted afternoon. Each item below looks like a supported extension point. None of them is wired to anything.

There is no Automation_context class

The handler interface's docblocks say @param object $context Automation_context. That name refers to no class anywhere in the tree. The first specification draft declared typed parameters — preview(Automation_context $context, …) — and following it produced a fatal, because the executor passes a plain stdClass-style object it assembles itself. The type hint was removed; the docblock name survives as a label for the shape.

// modules/Automations/libraries/contracts/Automation_handler_interface.php
/**
 * @param object $context Automation_context      <-- a NAME, not a class
 */
public function preview($context, array $config);

Read the properties the executor actually sets before you use one. The M3 verification caught a handler reading $context->title, which does not exist — the executor sets automation_title. Nothing errored; the audit remark would simply have been blank forever.

Nothing reads publish_permissions

The HumanResource sidecar declares it, and its comment describes exactly the behaviour a reader would want:

// modules/HumanResource/config/automations.php
// Extra permissions the PUBLISHER must hold to publish a LIVE automation of this
// type; automations_publish is always required on top. Revalidated at run time,
// so a lapsed permission pauses the automation rather than continuing on the
// publisher's behalf.
'publish_permissions' => array(
    'approve' => array('attendance_approval'),
    'reject'  => array('attendance_approval', 'attendance_update'),
),

A repository-wide grep finds the key in exactly two files: the sidecar that declares it and the contract docblock that documents it. No consumer. The consequence is concrete and worth stating plainly:

Nothing applies defaults

defaults is the richest, best-commented block in the HumanResource sidecar — action, run_mode, overlap_policy, lookback_days: 7, settle_hours: 12, overtime_policy: skip, each with the measurement or the reasoning behind it. It is read by nothing. The same defaults are re-hardcoded in the builder view (views/automations/builder_modal.php writes 7 and 12 as literal value attributes and 'skip' as the dropdown's selected option). The numbers agree today; nothing keeps them agreeing.

Four of five capabilities keys are unread

Declaring 'preview' => false will not stop the builder previewing; declaring 'chunked' => false will not stop the executor chunking. The capability contract is one key wide.

The two version columns are hardcoded on save

// modules/Automations/controllers/Automations.php  (save)
"definition_version"    => 1,
"config_schema_version" => 1,

Both columns exist to detect that a stored automation was authored against an older definition. The registry does read the sidecar's own definition_version / config_schema_version when composing its checksum — but the automation row is stamped 1 unconditionally, so a comparison between the two would be meaningless. Clone copies the source row's values faithfully, which is correct and also inherits the 1. Do not build a migration path on these columns until save() reads them from the definition.

The reason-code vocabulary validates nothing, and has drifted

automations_reason_codes() in the module helper returns 17 codes. Reason codes actually arrive from three sources, and the declared list matches none of them cleanly, because record_item() validates outcome but writes reason_code verbatim.

Five codes the handler emits every run — APPROVED, NOT_YET_SETTLED, OVERTIME_PRESENT, RULE_NOT_MET, TRANSITION_ERROR — are absent from the declared list. Nine declared codes are emitted by nobody: MISSING_TIME_IN, MISSING_TIME_OUT, OVERLAPPING_ATTENDANCE, ATTENDANCE_ANOMALY, LEAVE_CONFLICT, OUTSIDE_SCOPE, STATUS_CHANGED, ALREADY_SATISFIED, MUTATION_VALIDATION_FAILED. The list has exactly one consumer — a test asserting the vocabulary reflects features that exist. Harmless at runtime today; it will produce wrong labels the moment any UI renders from it. That is debt item 20.8.

The builder is hardcoded to one type

The wizard's Action and Safety panels render lookback_days, settle_hours, overlap_policy and overtime_policy as literal fields with literal defaults and literal bounds (min="1" max="365", min="0" max="720"). Those are the attendance type's fields. The rest of the module is registry-driven; this view is not. A second registered type needs these panels made registry-driven first — otherwise it either inherits attendance's configuration shape or gets no configuration UI at all.

The known-debt register

Plan §20. Each item is verified, each has an owner, and each is a deliberate compromise — not an oversight. Fixing one without reading its rationale is how a safe system becomes an unsafe one.

Decisions you might otherwise try to reverse

Each of these looks, at first glance, like something that should have been done the other way. Each was driven by a verified repository fact, so reversing one means re-checking that fact first.

One cron job, not a custom dispatcher

The original external draft specified a cron registration file, a distributed lock, a heartbeat table, a provider due-index and a catch-up policy. ERPat's Advanced Cron runtime already provides every one of them. The module registers a single JobContract class and nothing else. Both provider-level tables were dropped for the same reason: Tick already fans out per tenant with the database switched, so the job reads the current tenant's own table, and liveness is /cron/health plus cron_runs. Per-automation schedules reuse App\Cron\Core\CronExpression — it is ERPat's single parse authority, and a second parser would drift.

Publisher authority, not a service principal

The draft wanted a "virtual service principal". ERPat has no service-principal primitive, and inventing one is not a module's job. What is buildable today is publish-time and run-time revalidation of the publisher's own permissions, with the audit actor being the seeded System user. This has a property a service principal would not: authority fails closed — a publisher who is deleted, deactivated or stripped of automations_go_live moves the automation to needs_review and fails the run PUBLISHER_UNAUTHORIZED, rather than continuing to approve records on the authority of someone who has left.

Plural, slug-keyed permission names

The plan first specified singular keys; the shipped keys are plural (automations, automations_create, …). The make:module default and the majority ERPat precedent both key permissions to the module slug (Todo→todo, Notes→note; Assets→asset is the outlier), and keeping the base equal to the slug removes a singular/plural split between with_module() and with_permission().

Administration placement, and its three core-side companions

The plan originally put the module in the Productivity group. It ships in Administration, between System Logs and Settings, with category "System" — because the Automation Center configures how ERPat acts on its own records. That is governance, not a productivity app, and it reads naturally beside the other two system surfaces.

The move required three core-side companions, and a future reader relocating this item needs all three:

The item name was unchanged by the move, so no saved custom menu was orphaned and no remap migration was needed. Three contract tests pin the placement across the module config and both core lists.

Approve-only, and the scaffolding that stayed

Phase 1 ships no Reject action. Attendance_auto_decision_handler::validate_config() refuses any other action with automation_error_action_not_supported. The reasoning: an Observe run can prove a rule selects the right records, but it cannot prove a rejection is correct — and a wrong rejection withholds earned pay invisibly until payday.

The forward-compatible scaffolding is deliberate and should not be tidied away: rejected_count and would_reject on the run tables, publish_permissions['reject'] in the sidecar, and the paused demo-seeder row.

The overtime policy destroys nothing

Worth restating here because it is the decision most likely to be misread as a data bug. The measured overtime hours are always stored. The policy records a decision about them in attendance_metrics.ot_status, and unapproved hours are withheld at read time. So skip (the default) decides nothing and queues the record for a person; exclude approves base hours and rejects the overtime; include approves both. No policy erases a number, and every choice is reversible from the Overtime tab.

Idempotency without a revision column

The draft's staleness guard assumed an attendance revision number. The attendance table has no revision, created_at or updated_at column, so the guard was reformulated: a transactional status re-read immediately before the write, plus UNIQUE(run_id, subject_type, subject_id) for per-run dedupe. Similarly, the draft's "pending attendance correction request" rule was dropped outright — that feature does not exist in ERPat — and replaced with "no pending schedule change request", which does.

Re-verifying this page

This page ages the moment M4 starts. Before trusting it against an unfamiliar checkout, re-run the three cheap checks that would catch most drift:

# 1. Is the phantom still phantom? Each of these should return the DECLARING
#    file and the docblock only — never a consumer.
grep -rn "publish_permissions" --include=*.php modules/
grep -rn "Automation_context"  --include=*.php modules/

# 2. Have the reason codes converged? Compare the declared vocabulary
#    against what the handler and the executor actually emit.
grep -n "automations_reason_codes" -A 25 modules/Automations/helpers/automations_helper.php
grep -oP "'[A-Z_]{4,}'" modules/HumanResource/automation/Attendance_auto_decision_handler.php | sort -u

# 3. Has M4 landed? Any of these existing means this page is out of date.
ls modules/Automations/config/notifications.php \
   modules/Automations/config/api_routes.php \
   modules/Automations/config/api_scope.php \
   modules/Automations/controllers/Automations_api.php 2>/dev/null

Then re-read modules/Automations/specs/automation-center-status.md §1 for the milestone table and §20 of the implementation plan for the debt register. Both are maintained as work lands; this page is a reading of them at a point in time.

The one question still open

Three of the four open questions closed during implementation: the module name stays "Automation Center", the transition-service extraction was accepted and owned by HumanResource, and Phase 1 is approve-only. One remains: which tenant and which department host the observe-versus-human comparison pilot. Owner: Operations. Needed by M5, and it is the last thing between the module and a staged rollout.