## Problem/Motivation The module implements one delete mechanism and offers no way to vary it per mapping. **Detection is absence-only and global.** `ApiSyncDeleteProvider` enumerates every remote key for a mapping's object type and deletes every mapped object the remote did not return. A remote that soft-deletes — flagging a record rather than removing it — never triggers detection at all, because the flagged record is still returned. The provider is a single service (`apisync_mapping.services.yml:20`), so a site with a mix of remote types cannot vary it and must patch the module. **Execution is `DELETE`-only.** `ApiSyncMappedObject::pushDelete()` calls `ODataClientInterface::objectDelete()`, which always issues `DELETE` (`src/OData/ODataClient.php:463`). A remote whose deletion is a status write needs `PATCH`. There is no event, no plugin and no setting anywhere on that path. **The cron delete path never contacts the remote.** This is the part that makes the other two insufficient on their own. `DeleteHandler::handleMapping()` marks the entity as syncing (`:159-161`), which makes `apisync_push_entity_crud()` return early (`apisync_push.module:57-66`) so nothing is queued, and then deletes the mapped object (`:177`), which is what holds the remote path. Both are correct when the remote already dropped the record. Both are wrong when the remote is *asking* Drupal to delete and expects an answer: the record keeps its flag, is re-detected on every subsequent run, and the remote never learns the deletion completed. **The advertised veto does not exist.** `ApiSyncEvents::DELETE_ALLOWED` is declared with a full docblock and `ApiSyncDeleteAllowedEvent` is a complete class with `disallowDelete()`. Nothing dispatches it — verified across `*.php`, `*.module`, `*.inc` and `*.install`. Its sibling `PUSH_ALLOWED` is dispatched and honoured, so the asymmetry is not deliberate. The event's accessor is also phrased as a prohibition rather than a permission, unlike the other two veto events, and its docblock is inverted against its own return value. A downstream patch already built against it and got it wrong, which is the evidence that the shape misleads. ## Proposed resolution A single plugin type owned by `apisync_mapping`, selected and configured per mapping, carrying both halves of the delete protocol. `apisync_pull` and `apisync_push` both depend on `apisync_mapping` and neither on the other, and both delete call sites already live in `apisync_mapping`. So the plugin adds no coupling: push keeps owning *when* a delete is sent, and the plugin owns *what a delete means* for this remote. **Plugin type** `Plugin/ApiSyncDeleteStrategy`, attribute-based (`DefaultPluginManager` warns that annotation-only managers are deprecated in 11.2 and removed in 12), manager service `plugin.manager.apisync_delete_strategy`, fallback plugin `broken`. **Interface**, three methods: | Method | Called from | Base default | | --- | --- | --- | | `getMappedObjectIdsToDelete(ApiSyncMappingInterface $mapping): array` | `DeleteHandler::handleMapping()` | abstract | | `deleteRemoteRecord(ApiSyncMappedObjectInterface $mappedObject): void` | `ApiSyncMappedObject::pushDelete()` | today's `objectDelete($path)` | | `acknowledgesDelete(): bool` | `DeleteHandler::handleMapping()` | `FALSE` | `acknowledgesDelete()` is what fixes the third problem above. When it returns TRUE, the handler does not mark the entity as syncing and does not retire the mapped object, so the push module queues the deletion and the strategy's `deleteRemoteRecord()` sends the acknowledgement. Queued rather than inline, so the acknowledgement is never sent before the local delete has committed. **Two strategies ship in the module.** `absence` is the default and reproduces today's behaviour. `remote_flag` covers a remote that flags its deletions, configured with the field name, the value meaning deleted, and the value written back. A site with a flagged remote therefore needs configuration, not code. **`broken`** is the fallback when a plugin's provider is uninstalled. It deletes nothing on either half and does not throw, because `pushDelete()` runs inside a try that re-enqueues on failure and a throwing fallback would produce a push queue item that can never drain. Falling back to `absence` is never acceptable: an absence run against a mapping configured for a flagged remote enumerates unfiltered and would delete everything. **`DELETE_ALLOWED` is dispatched** in `DeleteHandler` before each delete. A veto skips the whole iteration — entity and mapped object both survive — and dispatches a notice, matching what `createEntity()` already does when `PULL_PREPULL` refuses. `isDeleteProhibited()` becomes `isDeleteAllowed(): bool`, and the docblock is corrected. **Four safety guards land on the `absence` strategy**, because absence infers deletion from a negative and a broken query reads as "delete everything". They refuse a response holding no records, a run that ended on a non-terminal page, a mapping with no key fields configured, and a mapping whose key field configuration changed since the last good run. Each aborts the mapping's run, leaves the watermark untouched, and dispatches an error naming the guard. `remote_flag` needs none of them — it acts on a positive assertion, so a broken query under-deletes and self-heals — but does get one of its own: it refuses to run when it would have to acknowledge a delete on a mapping that has no `push_delete` trigger, since the acknowledgement could never be sent. ## Remaining tasks - [ ] Dispatch `DELETE_ALLOWED`; rename `isDeleteProhibited()` to `isDeleteAllowed()`; fix the docblock. - [ ] Name the error events the delete path dispatches, and keep a refused entity delete from also losing its mapped object. - [ ] Refuse to reconcile against a response holding no records. - [ ] Add the plugin type: attribute, interface, manager, base class, `broken` fallback. - [ ] Move the absence reconciliation into the default plugin, selected per mapping; retire the global service. - [ ] Add `acknowledgesDelete()` and the handler behaviour it controls. - [ ] Add a mapping validation constraint for a strategy that must acknowledge on a mapping that cannot. - [ ] Add the `remote_flag` strategy, with its own delete watermark stored through `PullInfo`. - [ ] Add the remaining three absence guards. - [ ] Add the strategy select and its settings subform to the mapping form. - [ ] Kernel coverage for every behaviour above. ## User interface changes The mapping form gains a "Delete strategy" select in the existing pull section, defaulting to the current behaviour, plus an AJAX-rebuilt settings container supplied by the selected plugin — the same shape `ApiSyncAuthForm` already uses for auth providers. ## API changes - New plugin type `apisync_delete_strategy` with `ApiSyncDeleteStrategyInterface` and the manager service `plugin.manager.apisync_delete_strategy`. - `ApiSyncDeleteAllowedEvent::isDeleteProhibited()` is renamed to `isDeleteAllowed(): bool` and its return value inverted. Nothing dispatches the event today, so nothing can be depending on the current shape. - `ApiSyncEvents::DELETE_ALLOWED` becomes a live extension point. - `ApiSyncDeleteProviderInterface` and the `apisync_mapping.apisync_delete_provider` service are removed, replaced by the plugin type. This breaks anyone injecting that service by id. - `ApiSyncMappingInterface` gains `getDeleteStrategyId()`, `getDeleteStrategySettings()` and `getDeleteStrategy()`. ## Data model changes `apisync_mapping` config entities gain `delete_strategy` (string, default `absence`) and `delete_strategy_settings` (array), both exported. The settings key uses a dynamic schema type keyed on the selected strategy, with an `ignore` fallback so a site's orphaned settings survive a save — the pattern `apisync.schema.yml` already uses for auth provider settings. No update hook is required: an existing mapping with no `delete_strategy` key takes the property default and behaves exactly as it does today. This follows `page_size`, which shipped the same way. ## Out of scope Each of these is its own issue: - Threshold, count-corroboration and candidate re-query guards on the absence strategy. They need either a number measured against a real mapping's churn or an extra request per run, and this issue should not wait on that. - The `apisync_mapping_ui` link template, which checks `hasLinkTemplate('canonical')` and then hardcodes a path anyway. - Request logging with a redacted auth header. - A read-only mode for `ApiSyncMappedObject::push()` and `::pushDelete()`. - `apisync.api.php`, which does not exist; thirteen events and, after this, four plugin types are documented nowhere for an implementer. - `DeleteHandler::processDeletedRecords()` using `loadMultiple()` rather than `loadCronPullMappings()`, so a `pull_standalone` mapping is still reconciled by cron. ## Related - https://git.drupalcode.org/project/apisync/-/work_items/3595382 — test coverage (merged) - https://git.drupalcode.org/project/apisync/-/work_items/3595383 — merge `apisync_mapping_ui` into `apisync_mapping`; moves every mapping form class - https://git.drupalcode.org/project/apisync/-/work_items/3595384 — defect fixes; its delete hunks are taken by this issue instead - https://git.drupalcode.org/project/apisync/-/work_items/3595386 — pull watermark; supplies the `PullInfo` structure this issue stores its delete watermark in - https://git.drupalcode.org/project/apisync/-/work_items/3595387 — bounded pages; supplies the terminality and count plumbing the guards use