lmxopcua/docs/Reservations.md

# External-ID Reservations

The reservation subsystem guarantees that an asset's **external identifiers**
— its `ZTag` and `SAPID` — belong to exactly one piece of equipment across the
entire fleet, for all time. It is the mechanism that stops two pieces of
equipment (in the same cluster or different clusters, in the current generation
or an old one) from silently claiming the same plant tag.

This is **decision #124** in `docs/v2/plan.md`.

## What a reservation is

An `ExternalIdReservation` row is a permanent, fleet-wide claim on one
identifier value by one `EquipmentUuid`. There are two kinds
(`ReservationKind`):

| Kind    | What it is |
|---------|------------|
| `ZTag`  | The plant's tag identity for a physical asset. |
| `SAPID` | The asset's SAP record ID. |

An `Equipment` row may carry a `ZTag`, a `SAPID`, both, or neither. Whenever it
carries one and the generation is published, a reservation is created for that
value.

## Why it sits outside the generation flow

Every other part of the configuration is **generation-versioned** — authored in
a draft, promoted by publish, superseded by the next publish, and reversible by
rollback. Reservations deliberately are **not**.

The reason: a single ZTag can legitimately appear in many places at once — the
current published generation, several superseded generations, and a piece of
equipment that has since been disabled. A per-generation uniqueness index would
fail the instant you roll back to an older generation or re-enable disabled
equipment, because the "old" copy of the identifier is still on disk.

So the reservation table is a flat, fleet-wide ledger that lives *beside* the
generation flow. It is append-mostly: rows are created, their `LastPublishedAt`
is refreshed, and they are eventually *released* — but never silently deleted.

## The table

`ExternalIdReservation` (Config DB):

| Column             | Notes |
|--------------------|-------|
| `ReservationId`    | Surrogate PK (`NEWSEQUENTIALID()`). |
| `Kind`             | `ZTag` or `SAPID`. |
| `Value`            | The reserved identifier string. |
| `EquipmentUuid`    | The equipment that owns the claim. Stays bound even when that equipment is disabled. |
| `ClusterId`        | The first cluster to publish the reservation. |
| `FirstPublishedAt` / `FirstPublishedBy` | When and by whom the claim was first made. |
| `LastPublishedAt`  | Refreshed on every subsequent publish that re-asserts the same `(Kind, Value, EquipmentUuid)`. |
| `ReleasedAt` / `ReleasedBy` / `ReleaseReason` | Non-null once a FleetAdmin explicitly releases the claim. A row with `ReleasedAt IS NULL` is *active*. |

There is no foreign key from `EquipmentUuid` / `ClusterId` to their tables — by
design, so a reservation survives the deletion or disabling of the equipment
that owns it.

## Lifecycle

### 1. Authoring

You give an `Equipment` row a `ZTag` and/or `SAPID` in a **draft** generation —
either by hand in the draft editor or via equipment CSV import. Nothing is
reserved yet; the draft is just a proposal.

> Equipment CSV import does **not** pre-check reservation conflicts (tracked as
> task #197). A conflict introduced by import surfaces at publish time, below.

### 2. Publish precheck

`sp_PublishGeneration` runs the draft validation first. If a `ZTag` or `SAPID`
in the draft is already reserved — `ReleasedAt IS NULL` — by a **different**
`EquipmentUuid`, the publish is rejected:

```
BadDuplicateExternalIdentifier: a ZTag in the draft is reserved by a
different EquipmentUuid
```

The same value owned by the *same* `EquipmentUuid` is fine — that is just the
asset keeping its identifier across generations.

### 3. Publish (the reservation is created)

When the publish succeeds, `sp_PublishGeneration` runs a `MERGE` into
`ExternalIdReservation` for every `ZTag`/`SAPID` in the published generation:

- **New** `(Kind, Value, EquipmentUuid)` → a reservation row is **inserted**.
  `FirstPublishedBy` is the publishing user; `ClusterId` is the publishing
  cluster.
- **Already present** → only `LastPublishedAt` is bumped.

So the *first* publish of an equipment carrying a ZTag is what claims that ZTag
for the fleet. After that the claim is permanent — it survives the equipment
being disabled, the generation being superseded, or a rollback.

### 4. Release

Reusing an identifier for a **different** piece of equipment requires a
FleetAdmin to explicitly release the existing claim. Release runs
`sp_ReleaseExternalIdReservation`, which:

- Requires a non-empty **reason** — a hard audit invariant; the procedure
  raises an error without one.
- Stamps `ReleasedAt`, `ReleasedBy` (`SUSER_SNAME()`), and `ReleaseReason`
  rather than deleting the row, so the history is preserved.
- Once released, the `(Kind, Value)` pair is free — a different
  `EquipmentUuid` can claim it on a future publish.

Release the claim **only** when the physical asset is permanently retired and
its identifier genuinely needs to be reused. A reservation is meant to be
permanent for the life of the asset.

## The Admin page

`/reservations` (Admin UI) is the operator surface. It is **FleetAdmin-only**
(the `CanPublish` policy).

- **Active** table — every reservation with `ReleasedAt IS NULL`: kind, value,
  owning `EquipmentUuid`, cluster, and the first/last publish stamps. Each row
  has a **Release…** action.
- **Released** table — the 100 most recently released reservations, with the
  releasing user and reason.
- **Release dialog** — opened from an active row; it requires a reason before
  the Release button will submit, mirroring the procedure's audit invariant.

You cannot *create* a reservation from this page — reservations only ever come
into existence as a side-effect of publishing a generation. The page is for
inspection and for the release flow.

## Related

- `docs/v2/plan.md` — decision #124 (reservations outside the generation flow).
- `docs/v2/admin-ui.md` — § "Release an external-ID reservation".
- `docs/v2/config-db-schema.md` — full Config DB schema.
- `OpcUaServer.md` — generations, draft/publish flow.