How the asset ↔ CI link (#201) is built, and the rules a change must keep. The user page is Linking an asset to its configuration item; the reasoning is in the design.

In one breath: one table of periods (asset_ci_links), one service (AssetCiLinkService) behind the asset page, the CI page and REST, and one JS card (CiAssetLink) drawn on both pages. The link is an identity. It is never an edge in the CMDB graph.

🗄️ schema · 🧠 rules · ✏️ write paths that call in · 🔌 REST · 🖥️ UI · 🧪 tests

What you don't touch: includes/cmdb_impact.php. The asset is not in the graph, so the impact walk never learns about the link. The asset card simply asks the CI's own blast radius.

One live link per asset and per CI is enforced in the service, not the schema (MySQL has no partial unique index). Every write locks the asset row, then the CI row (FOR UPDATE), then the live link rows, in that order everywhere, including unlink() from the CI side, which re-reads under the lock.

The service never reads a session or a key. It takes an ActorContext (company scope) and an access array:

['assets_read' => bool, 'cmdb_read' => bool, 'assets_write' => bool, 'cmdb_write' => bool]

Restriction is decided by the other side's read flag: from the asset, cmdb_read; from the CI, assets_read. When it is false, everything about the other end becomes {restricted: true}: the current link, every history entry, conflict messages ("…linked to an asset you cannot open"), and REST blocks. Ids are dropped too: a restricted block never carries an id.

The asset card setting (cmdb_asset_card_fields) only filters which details assetView() returns. It is applied after the access decision, so it can never widen access.

link(asset, ci, replace, replaces[])
  lock asset, lock CI, same company?            -> different_company
  asset's live link is this CI?                 -> unchanged (idempotent retry)
  conflicts = live link on asset + live link on CI
  conflicts and not replace                     -> ci_already_linked / asset_already_linked
  replace and sorted(conflicts) != sorted(replaces) -> link_changed
  close each conflict 'replaced', insert, history lines

replaces is exactly what the person saw. A refused link sends back conflictIds() (ids only, which say nothing about the record), the UI confirms and resends them. If anyone changed the link in between, the sets differ and nothing happens.

createLinkedCi() holds one transaction: lock the asset → already linked? return that CI (created: false, the retry case) → the type's class (mappedClass(), active only) or no_class_mapped → possible_matches unless ignore_matches → CmdbService::createInTransaction() → link() → commit → then CmdbService::announceCreated().

createObject() now begins and commits only when it owns the transaction, so it can run inside this one; createInTransaction() also holds back the cmdb.object.created workflow event, so a create that rolls back - a required property the CMDB refuses, a link that fails - never announces a CI that does not exist. CmdbService::requiredProperties() is what the form asks for.

$expectedLinkId (the card's link_id) must still be the live link, or link_changed. REST takes it as ?link_id=; leaving it out unlinks whatever is live.

CmdbService::deleteObject() → AssetCiLinkService::ciDeleted($ids) for the CI and every descendant, inside the delete's transaction and before any row goes, because close() reads the CI's name and class. Then clearAssetRefFields() deletes asset_field_values of ref fields whose config.ref_kind is cmdb_object pointing at those ids, with a field:<key> history row storing the id (as other link-field history rows do).

AssetMergeService::merge(..., $ciLinks) with $ciLinks = ['seen' => [...], 'keep_link_id' => N]:

• seen given and not equal to the live links of the two assets → ci_link_changed
• both linked and keep_link_id is not one of them → ci_link_choice_required (also what a caller passing null gets)
• the other link is closed asset_merged, then every row's asset_id moves to the kept asset

Neither CI is touched. Both errors throw inside the merge's transaction, so nothing is merged.

asset_history rows for the link use field_name = 'cmdb_link' and values ci:<id>, never a name. historyValue() resolves them per reader: the CI's name (live, or ci_name from the link row once it is deleted) for someone who can open the CMDB, a restricted configuration item for someone who cannot, and for REST ci:<id> or restricted. If you add another place that shows asset history, run it through historyValue().

• TRAP: the merge guard. A new column naming an asset in asset_ci_links must go in REFERENCES or NOT_REFERENCES, or tests/asset-merge.php fails. That is the point: original_asset_id must not move.
• TRAP: ciDeleted() before the deletes. Called after, close() finds no CI and the history row loses its name.
• TRAP: no PUT. The API router, its CORS header and the method override only know GET/POST/PATCH/DELETE (and IIS often blocks PUT), so linking is POST /assets/{id}/ci-link. It is still safe to retry.
• TRAP: a static call resolves its class before its arguments. AssetCiLinkService::restBlock($conn, apiAssetCiAccess($key), …) fatals if the class is loaded only inside apiAssetCiAccess(). The resource file requires the service at the top.
• Headless screenshots of the CI page stop after the fourth section: its entry animation never finishes without a compositor. Use --force-prefers-reduced-motion.

Hyper-V discovery binds CIs to discovered objects with the same shape: periods, actor and source at both ends, restricted readers, a decision refused if the state it was made on changed. An integration that links assets calls AssetCiLinkService::link() with link_source = 'integration:<name>' and an access array saying it may write. It never links on a name alone.