Service Layer Progress

Service Layer — progress tracker

Rollout status of the service-layer refactor: collapsing each module's duplicated UI + REST API write logic into one shared service, module by module, behind a before/after parity harness.

Strategy: prove the pattern on the smallest, lowest-risk module first; do tickets last (biggest, most integrations). Each module is its own revertable commit; nothing ships unless the harness proves the API is byte-identical.

Per-module status

Module	Status	Adapter lines removed	Parity	Notes
Service Status	✅ Done (#718)	474 removed / 75 kept (9 files)	✅ byte-identical	Pilot. Established the primitives + pattern. Display-UTC fix #719.
Morning Checks	✅ Done (#720)	424 removed / 94 kept (10 files)	✅ byte-identical	Unified documented UI/API drift. Added ActorContext.actorName + shared apiFailFromService().
Software	✅ Done (#722)	175 removed / 40 kept (3 files)	✅ byte-identical	Only licences overlap UI+API; inventory is read-only and widgets/apikeys are UI-only (no twin), so left untouched.
Calendar	✅ Done (#723)	302 removed / 70 kept (5 files)	✅ byte-identical	Events overlap UI+API; UI-only categories folded in. Naïve-local datetime contract preserved (not converted to UTC).
Forms	✅ Done (#724)	722 removed / 55 kept (6 files)	✅ byte-identical	Largest so far. Positional field sync + version chains + the form.submitted workflow dispatch all in one write path.
Contracts	✅ Done (#725)	462 removed / 56 kept (6 files)	✅ byte-identical	Contracts + suppliers + term upsert. Lookup settings (UI-only) and supplier contacts (UI-flat vs API-nested mismatch) left on their own code.
Knowledge	✅ Done (#726)	453 removed / 53 kept (4 files)	✅ byte-identical	Articles + tags + save-as-version + archive/restore/purge. Embedding regen (side effect) preserved with its decryptValue() guard.
Tasks	✅ Done (#728)	619 removed / 51 kept (4 files)	✅ byte-identical	Task CRUD + move + comments + subtasks + task.completed dispatch. First service to use ActorContext.companyScope (ticket-link scope). reorder/toggle/lookups left UI-only.
CMDB	✅ Done (#729)	638 removed / 50 kept (5 files)	✅ byte-identical	Object CRUD (typed property system, 6 types) + descendant-tree delete + relationships. Service normalises both property shapes (API key-map + UI id-list). Classes/rel-types read-only, ticket-links API-only.
CMDB	⬜ Planned	—	—
Network Mapper	⬜ Planned	—	—
Assets	⬜ Planned	—	—
Changes	⬜ Planned	—	—
Problems	⬜ Planned	—	—
Service Status settings	✅ folded into pilot	—	n/a	Incident-statuses + impact-levels are UI-only; moved into the service.
Tickets	⬜ Last	—	—	Biggest payoff, most integrations — deliberately last.

Line savings — the honest picture

The first module is roughly line-neutral: it pays a one-time cost (the shared ActorContext + ServiceError primitives, ~105 lines) and its service includes UI-only logic that was never duplicated. The thousands of lines of net removal arrive as the larger, heavily-mirrored modules migrate — tickets above all.

	Lines
One-time primitives (includes/service_context.php + apiFailFromService)	+122 (paid once, for all modules)
Service Status: adapter logic removed	−474
Service Status: adapters kept (thin)	+75
Service Status: service (incl. UI-only ops)	+390
Morning Checks: adapter logic removed	−424
Morning Checks: adapters kept (thin)	+94
Morning Checks: service (incl. UI-only ops)	+310
Software: adapter logic removed	−175
Software: adapters kept (thin)	+40
Software: service (licences only)	+168
Calendar: adapter logic removed	−302
Calendar: adapters kept (thin)	+70
Calendar: service (events + UI-only categories)	+251
Forms: adapter logic removed	−722
Forms: adapters kept (thin)	+55
Forms: service (forms + versions + submissions + dispatch)	+445
Contracts: adapter logic removed	−462
Contracts: adapters kept (thin)	+56
Contracts: service (contracts + suppliers + terms)	+341
Knowledge: adapter logic removed	−453
Knowledge: adapters kept (thin)	+53
Knowledge: service (articles + recycle bin)	+299
Tasks: adapter logic removed	−619
Tasks: adapters kept (thin)	+51
Tasks: service (tasks + move + comments)	+506
CMDB: adapter logic removed	−638
CMDB: adapters kept (thin)	+50
CMDB: service (objects + properties + relationships)	+472

Convergence log

Where a module's UI and API already behaved differently, we converge to the API's behaviour (the API is the external contract; it stays identical, the UI shifts to match). Record each convergence here so nothing is a silent surprise.

Service Status (#718):

• Create timestamps: server-local → UTC (SLA-correct; same bug class as Forms #701).
• Empty description: "" → null.
• Affected-service validation: silently-skip unknowns → strict 422.
• Incident status: name-only → name or id.
• UI deletes: idempotent → 404 on missing (matches the API).

Morning Checks (#720):

• Result date: malformed silently-swapped-for-today → strict 422.
• Unknown check id on a result: raw FK 500 → 422 with a clear message.
• Result CreatedBy: left NULL by the UI → the recording analyst's name (attribution; the API already did this).
• Check validation messages align with the API wording; updating/deleting a missing check → 404 (was a silent no-op).

Software (#722):

• Licence app id: no check (raw FK error on a bad id) → the app must exist, 422 with a clear message.
• Quantity / cost / dates: silently coerced → validated (422) — a negative quantity, a non-numeric cost or a malformed date is rejected.
• Empty optional fields (licence_key, portal_url, vendor_contact, notes): stored as "" → null; missing currency/status fall back to GBP / Active.
• Saving or deleting a missing licence: silent success → "Licence not found." (matches the API's 404).

Calendar (#723):

• Event category id: no check (raw FK error on a bad id) → the category must exist, 422.
• Event times: no check → end_at before start_at is rejected (422); naive-datetime format is validated (Z/offset rejected) — the naive-local contract is kept, not converted to UTC.
• Generated events (source = 'asset_warranty' etc.): the UI let you edit/delete one, only for it to reappear on the next sync → now refused (409) on both edit and delete, matching the API.
• Saving or deleting a missing event: silent success → "Event not found." (matches the API's 404).
• Categories are a UI-only operation (no API twin) — moved into the service with behaviour preserved verbatim (name required, #RRGGBB colour check, in-use delete guard).

Forms (#724):

• Field validation: a blank label was silently dropped, an unrecognised field type blindly stored → both now 422.
• Submission with an unknown field id: raw FK error → 422 with a clear message.
• Editing a frozen (non-leaf) version → 409; deleting a form that still has newer versions → 409 (was a raw FK error). Whole-chain delete stays an API-only option (?chain=true).
• Submitting to an inactive form → 409 (the UI merged not-found + inactive into one message; now split into 404 / 409).
• Saving/deleting a missing form or submission → 404 (was a silent success).
• The form.submitted workflow dispatch now fires from the shared write path, so UI and API submissions trigger workflows identically — the first webhook-relevant side effect to land on a service (see the eventing note above).

CMDB (#729):

• Dropdown property values are validated against the option list; date properties are parsed (both were previously stored as-is). Numbers, object_ref (existence / target-class / no-self-ref), required-property and parent-cycle rules were already shared behaviour.
• The service accepts both property input shapes and normalises them: the API's properties {key: value} map, and the UI's property_values [{property_id, value}] id-list (unknown ids dropped, as the UI did). Neither transport had to change its payload.
• Scope: class + property-definition design and relationship-type management stay UI-only admin (the API exposes classes + rel-types read-only); the object↔ticket link endpoints are API-only (no UI twin). Both keep their own code.

Tasks (#728):

• Status / priority / tags / assignee / team are validated (unknown values were silently accepted or defaulted); dates validated; a task can't be its own parent.
• task→ticket links are now company-scoped in the UI too — the first use of ActorContext.companyScope in the service layer. A generic ticketAccessible($conn, $ctx, $id) mirrors apiKeyCanAccessTicket using the actor's scope (null = all, else the accessible tenant ids), so a UI session and an API key both enforce the same isolation. The UI previously stored any ticket id unchecked (a known MT gap) — now closed.
• The task.completed workflow fires from the shared write path exactly as before: on a PATCH that moves an open task into a closed status, not on a kanban move (the product's asymmetry, preserved).
• Scope: the UI drag (reorder.php) sends client-computed positions while the API's /move re-packs the column server-side — a structural mismatch — so it stays UI-only, along with the subtask-toggle convenience and the lookup settings.

Knowledge (#726):

• A title is now required and capped at 255 characters; the owner must be a real active analyst (was a raw FK error); the review date is validated.
• Editing an article that's in the recycle bin is refused (409 — restore it first); restoring a live article, or permanently-deleting one that isn't archived, returns a clear 409 instead of silently doing nothing.
• The OpenAI embedding regeneration (a best-effort side effect after each save) moved into the service. Follow-up #727: the service now requires encryption.php, so the embedding regenerates on both the UI and the API — previously the API path lacked decryptValue() and silently skipped it, leaving API-written articles invisible to AI search. It stays best-effort (runs after commit, swallows failures), so a missing/blank/invalid key never blocks the save.

Contracts (#725):

• A contract now needs a contract_number + title; its supplier / status / schedule / owner id must exist (were raw FK errors); dates are validated; the value must be numeric and the currency a 3-letter code.
• A duplicate contract_number is refused (409) on create and update — the raw UI allowed duplicates.
• Deleting a supplier cleanly unlinks every referrer (assets, contacts, contracts, RFP invites/scores) before the delete, and created timestamps are stamped UTC (the UI relied on the server-local column default).
• Scope: only the cleanly-duplicated overlaps (contracts, suppliers, term values) were migrated. The lookup settings (contract/supplier statuses, supplier types, payment schedules, term tabs) are UI-only (the API exposes them read-only) and stay on their own endpoints; supplier contacts are modelled flat by the UI (a supplier_id in the body, movable) but nested under a supplier by the API — a structural mismatch not worth forcing into one shape — so they stay separate too.

Deferred / follow-up work

• Display-layer UTC parsing — storage is now consistently UTC, but module JS parses "Y-m-d H:i:s" as local (new Date(...)), so UTC data can render an hour off. Fix is a small per-module parseUtc() helper (mark the naive string UTC before toLocale*). Done for service-status (#719); still to do on calendar, morning-checks and other timestamp-rendering modules. See Watch out for #2.
• Webhook events from the write path — once a module is on its service, emitting lifecycle events (for outbound webhooks) is one line from the single write path, firing identically for UI, API and automation. This is the webhooks "wider event catalogue" phase.

How each module is done

1. Read the complete surface — every UI endpoint and the API resource for the module.
2. Enumerate the UI-vs-API divergences; agree the convergence.
3. Build/adapt the parity harness; capture golden-before on untouched code.
4. Extract <Module>Service; repoint the API write handlers + the UI endpoints at it.
5. Run the harness after; require the API byte-identical, UI converged as designed.
6. Ship as one commit. Update this page.

See Service Layer — architecture for the conventions and the full "Watch out for…" list.