feat: split cache deletion into swap and update job types

CONTEXT.md

@@ -0,0 +1,55 @@
+# Context
+
+Glossary for the Raster domain as this package models it. Terms only — no implementation
+detail, no specification. If a term here disagrees with the code, one of them is wrong.
+
+## Deletion
+
+**Layer deletion** — Removing a layer from the system entirely: its catalog record, its
+serving configuration, its polygon parts, and its stored resources. Terminal; the layer
+ceases to exist. Job type `Delete_Layer`.
+
+**Cache deletion** — Invalidating entries in the Redis tile cache so that stale tiles stop
+being served. The layer itself survives. Distinct from layer deletion in both intent and
+lifetime: cache deletion is routine maintenance that follows a change to a live layer, not
+the retirement of one.
+
+**Swap cache invalidation** — Cache deletion following a layer _swap_, where the layer's
+tiles were replaced wholesale. Every cached entry for the layer is stale, so the whole key
+prefix is removed. Job type `Swap_Delete_Cache`.
+
+**Update cache invalidation** — Cache deletion following an _in-place update_, where only
+part of the layer changed. Only the affected tiles are stale, so invalidation is scoped to
+a set of tile ranges. Job type `Update_Delete_Cache`.
+
+**Artifacts deletion** — Removing a layer's non-tile stored resources (GPKG files,
+metadata files, and similar) from their storage provider. Job type `Delete_Layer`, task
+type `artifacts-deletion`.
+
+**Tiles deletion** — Removing tile _files_ from a path-based store (S3 or FS), addressed by
+a base path, tile ranges, and a file extension. Not to be confused with cache deletion,
+which removes cache _entries_ from a key-value store and has no paths or file extensions.
+
+## Storage
+
+**Source type** — Where raster data originates: `S3`, `GPKG`, or `FS`.
+
+**Storage provider** — Where a deletion operation acts: `S3`, `FS`, or `REDIS`. Deliberately
+a separate term from source type: Redis is a deletion target but never a data source, and
+GPKG is a data source but never a deletion target. The two sets overlap without being equal.
+
+**Prefix** — The locator for a set of entries in a key-value store, as a path is the locator
+for a file. For the Redis tile cache, a prefix identifies every cached tile belonging to one
+layer in one grid.
+
+## Jobs and tasks
+
+**Job type** — What work was requested and why, chosen when the job is created. It reflects
+the upstream event (a swap happened, an update happened, a layer was retired).
+
+**Task type** — What kind of work a single unit performs.
+
+A task's parameter shape is determined by the **pair** of job type and task type, not by the
+task type alone. The same task type carries different parameters under different job types —
+this is deliberate, and it is why task types are not sufficient on their own to identify a
+unit of work.

src/constants/deletion/constants.ts

@@ -1,7 +1,18 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 export const DeletionJobTypes = {
   Delete_Layer: 'Delete_Layer',
-  Delete_Cache: 'Delete_Cache',
+  /**
+   * Cache invalidation following a layer swap: the previous cache is stale in its entirety.
+   * Paired with {@link DeletionTaskTypes.CacheDeletion}, whose task parameters are
+   * `redisDeleteStoredResourcesParamsSchema` — the key `prefix` alone locates everything to remove.
+   */
+  Swap_Delete_Cache: 'Swap_Delete_Cache',
+  /**
+   * Cache invalidation following an in-place layer update: only the updated tiles are stale.
+   * Paired with {@link DeletionTaskTypes.CacheDeletion}, whose task parameters are
+   * `redisTilesDeletionParamsSchema` — the key `prefix` plus the `ranges` to invalidate.
+   */
+  Update_Delete_Cache: 'Update_Delete_Cache',
 } as const;
 
 export type DeletionJobTypes = (typeof DeletionJobTypes)[keyof typeof DeletionJobTypes];
@@ -10,7 +21,13 @@ export const DeletionTaskTypes = {
   Delete: 'delete',
   LayerTilesDeletion: 'tiles-deletion',
   ArtifactsDeletion: 'artifacts-deletion',
+  /**
+   * Removal of entries from the Redis tile cache. The parameter shape is decided by the job type
+   * this task is paired with — see {@link DeletionJobTypes.Swap_Delete_Cache} and
+   * {@link DeletionJobTypes.Update_Delete_Cache}.
+   */
   CacheDeletion: 'cache-deletion',
 } as const;
 
 export type DeletionTaskTypes = (typeof DeletionTaskTypes)[keyof typeof DeletionTaskTypes];
+/* eslint-enable @typescript-eslint/naming-convention */