Skip to content

A free open source IT asset/license management system

60.9 KB
Raw Blame
<?php

namespace App\SyncAdapters;

use App\Models\Actionlog;
use App\Models\Asset;
use App\Models\AssetModel;
use App\Models\Category;
use App\Models\CustomField;
use App\Models\Manufacturer;
use App\Models\Statuslabel;
use App\Models\SyncAdapterConfig;
use App\Models\SyncAdapterInstance;
use App\Models\User;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use RuntimeException;

/**
 * Shared asset-side upsert path for every host-inventory adapter,
 * folded onto SyncAdapter via `use SyncsHostFromRecord;` so the entry
 * point sits on the base class. Accepts a normalized
 * HostInventoryRecord and either creates a new asset or updates an
 * existing one keyed on (source, external_id) in
 * asset_external_sources.
 *
 * The write path is deliberately dumb about vendors: no adapter-
 * specific logic lives here. Adapters do their own normalization and
 * hand a clean record over. Per-instance target mappings (configured
 * via MappingTargets on the settings page) let admins redirect each
 * normalized field to a custom field or skip it entirely. This trait
 * reads those overrides and dispatches values accordingly.
 */
trait SyncsHostFromRecord
{
    public static function syncFromRecord(HostInventoryRecord $record): ?Asset
    {
        return DB::transaction(function () use ($record) {
            $instance = SyncAdapterInstance::query()->where('slug', $record->sourceKey)->first();
            $mapping = self::loadMapping($instance);

            $provisioned = self::provisionAsset($record, $instance, $mapping);
            if ($provisioned === null) {
                return null;
            }
            [$asset, $isNew] = $provisioned;

            $externalUpdates = [];
            self::applyStandardFieldMappings($asset, $externalUpdates, $record, $instance, $mapping);
            self::applyExtraFieldMappings($asset, $record, $instance, $mapping);

            $previousExternal = $isNew ? [] : self::loadExternalSourceInventory($asset->id, $record->sourceKey);
            $wasDirty = $asset->isDirty();

            // Heartbeat-only asset-side write: Skip logging when heartbeat-logging is turned off,
            // when the mapping directs last_seen to a custom field (target custom:X).
            // Otherwise the vendor's heartbeat lands on the asset and fires AssetObserver::updating
            // on save, which writes an `update` Actionlog.
            if (! $isNew && self::isHeartbeatOnlyAssetDirty($asset, $mapping, $instance)) {
                if (! $asset->saveQuietly()) {
                    throw new RuntimeException('Failed to save asset during heartbeat-only sync.');
                }
            } else {
                // Asset::save() augments $this->rules with the model's
                // fieldset validation rules INSIDE the save call, so
                // Watson's saveOrFail() upfront isInvalid() check runs
                // before the augmentation and passes. It then delegates
                // to Eloquent's saveOrFail() which wraps save() in a
                // transaction WITHOUT re-checking the return value, so
                // when the ValidatingObserver aborts the save (returns
                // false) the whole chain silently returns false and the
                // sync counts the record as processed. Calling save()
                // directly and checking the boolean mirrors
                // createShellAsset()'s existing guard and surfaces the
                // real validation error to the pull loop's catch.
                if (! $asset->save()) {
                    $errors = implode('; ', $asset->getErrors()->all()) ?: 'unknown validation failure';
                    throw new RuntimeException("could not update asset for {$record->sourceKey} record {$record->sourceId}: {$errors}");
                }
            }

            // External-source column writes gather during the mapping
            // loop and go out together so we make one row-write per
            // sync instead of N updates.
            if ($externalUpdates !== []) {
                self::upsertExternalSource($asset, $record->sourceKey, $externalUpdates);
            }

            // Sync-driven user assignment. Runs after saveOrFail so
            // the asset is committed before we try to check it out.
            // Only touches assets whose adapter has a user-match
            // strategy configured. missing or unresolved users skip
            // silently after logging a warning.
            self::assignUserIfMatched($asset, $record, $instance);

            if (! $isNew) {
                self::logExternalSourceChanges($asset, $previousExternal, $externalUpdates, $wasDirty, $instance);
            }

            return $asset->refresh();
        });
    }

    /**
     * Resolve the asset for this sync record. Either finds it by the
     * existing (source, external_id) tuple in asset_external_sources
     * or creates a fresh shell asset + identity row for first-sync
     * cases. Also handles the update-sync group-reassignment case
     * where a device moved to a different vendor group that maps to
     * a different Snipe-IT company. Returns null when the record was
     * intentionally skipped (no match + create-on-pull disabled).
     *
     * @param  array<string, string>  $mapping
     * @return array{0: Asset, 1: bool}|null
     */
    private static function provisionAsset(HostInventoryRecord $record, ?SyncAdapterInstance $instance, array $mapping = []): ?array
    {
        $existingSource = DB::table('asset_external_sources')
            ->where('source', $record->sourceKey)
            ->where('external_id', $record->sourceId)
            ->first();

        $asset = $existingSource ? Asset::find($existingSource->asset_id) : null;

        if ($asset !== null) {
            // Update-sync path: if the vendor moved this device to a
            // different group and the new group maps to a different
            // Snipe-IT company, reassign. Same "vendor is
            // authoritative" model as native:asset_tag for tags.
            // Admins who want to preserve manual company assignments
            // turn off group scoping for this adapter or delete the
            // specific mapping.
            $resolvedCompanyId = self::resolveCompanyId($record, $instance);
            if ($resolvedCompanyId !== null && $resolvedCompanyId !== (int) $asset->company_id) {
                $asset->company_id = $resolvedCompanyId;
            }

            return [$asset, false];
        }

        // Migration path for customers moving from a homegrown
        // sync script. Their existing assets have a serial populated
        // but no asset_external_sources row for this adapter. When
        // the admin has turned on "adopt existing assets by serial",
        // look up a matching Snipe-IT asset before creating a fresh
        // shell. Establishes the identity link so subsequent syncs
        // treat this as an update, not a duplicate create.
        $adopted = self::adoptExistingAssetBySerial($record, $instance);
        if ($adopted !== null) {
            return [$adopted, false];
        }

        // Opt-out: when the admin has turned "Create new Snipe-IT
        // assets on sync" off, skip unmatched vendor records entirely
        // instead of creating a shell. Log at warning so admins can
        // spot drift between vendor + Snipe-IT inventories.
        $adapter = $instance?->adapter();
        if ($adapter instanceof SyncAdapter && ! $adapter->createsSnipeitAssetsOnPull()) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s sync: skipped %s record %s (no existing Snipe-IT match and asset creation on pull is off)',
                $adapter->name(),
                $record->sourceKey,
                $record->sourceId,
            ));

            return null;
        }

        // UX layer on top of the authoritative require_serial check
        // in Asset::save().
        if ($record->hardwareSerial === null || $record->hardwareSerial === '') {
            $modelName = self::resolveModelSourceValue($record, $mapping);
            if ($modelName !== null && $modelName !== '') {
                $existingModel = AssetModel::where('name', $modelName)->first();
                if ($existingModel !== null && (string) $existingModel->require_serial === '1') {
                    Log::channel('sync-adapters')->warning(sprintf(
                        '%s sync: skipped %s record %s (no serial, and asset model "%s" requires one)',
                        $adapter?->name() ?? $record->sourceKey,
                        $record->sourceKey,
                        $record->sourceId,
                        $existingModel->name,
                    ));

                    return null;
                }
            }
        }

        $asset = self::createShellAsset($record, $instance, $mapping);

        // Identity row created empty of inventory columns. the
        // mapping loop below fills them and the write goes out
        // through upsertExternalSource().
        DB::table('asset_external_sources')->insert([
            'asset_id' => $asset->id,
            'company_id' => $instance?->company_id,
            'source' => $record->sourceKey,
            'external_id' => $record->sourceId,
            // NULL for CLI / scheduled runs, admin id for
            // interactive Sync Now clicks.
            'created_by' => auth()->id(),
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        return [$asset, true];
    }

    /**
     * Look up an existing Snipe-IT asset with a matching serial to
     * adopt into this adapter's external-sources link, when the
     * admin has turned on adopt_by_serial for this adapter instance.
     *
     * Re-enrollment: some vendors rotate the device's external_id
     * (Intune managedDevice ID, Kandji device UDID, etc)
     * when the device is reinstalled or re-enrolled. On the
     * next sync the record's new external_id does not match the
     * asset's prior asset_external_sources row, so the (source,
     * external_id) lookup in provisionAsset misses. If the hardware
     * serial still matches and adopt_by_serial is on, treat the
     * prior row's external_id as stale and update it to the new one
     * rather than creating a duplicate asset.
     *
     * The genuine case of two actively-enrolled devices
     * legitimately sharing a serial (vendor cloning bug / BYOD) is
     * not handled here: the external_id will flap between the two
     * records across syncs. True fix is pull-level reconciliation :(
     */
    private static function adoptExistingAssetBySerial(HostInventoryRecord $record, ?SyncAdapterInstance $instance): ?Asset
    {
        if ($record->hardwareSerial === null || $record->hardwareSerial === '') {
            return null;
        }
        if ($instance === null) {
            return null;
        }

        $adapter = $instance->adapter();
        if (! ($adapter instanceof SyncAdapter) || ! $adapter->adoptsBySerial()) {
            return null;
        }

        $candidate = Asset::query()
            ->where('serial', $record->hardwareSerial)
            ->first();

        if ($candidate === null) {
            return null;
        }

        $existing = DB::table('asset_external_sources')
            ->where('asset_id', $candidate->id)
            ->where('source', $record->sourceKey)
            ->first();

        if ($existing !== null) {
            DB::table('asset_external_sources')
                ->where('id', $existing->id)
                ->update([
                    'external_id' => $record->sourceId,
                    'updated_at' => now(),
                ]);

            Log::channel('sync-adapters')->info(
                "{$instance->label} re-linked asset #{$candidate->id} (serial {$record->hardwareSerial}): external_id {$existing->external_id} -> {$record->sourceId}. Prior enrollment id appears to have rotated."
            );

            return $candidate;
        }

        DB::table('asset_external_sources')->insert([
            'asset_id' => $candidate->id,
            'company_id' => $instance->company_id,
            'source' => $record->sourceKey,
            'external_id' => $record->sourceId,
            'created_by' => auth()->id(),
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        return $candidate;
    }

    /**
     * Apply per-field mappings. Routes each normalized field to native
     * asset columns, external-source columns, custom fields, or skips
     * it, based on per-instance config. Fields directed 'push' or
     * 'skip' on this instance are excluded from the pull path so the
     * vendor's value can't overwrite a Snipe-IT-authoritative field
     * (asset_tag pushed to the vendor shouldn't get pulled back from
     * what the vendor reports). 'both' direction still pulls (naive
     * last-write-wins) so both sides converge on whichever side ran
     * most recently.
     *
     * @param  array<string, mixed>  $externalUpdates
     * @param  array<string, string>  $mapping
     */
    private static function applyStandardFieldMappings(
        Asset $asset,
        array &$externalUpdates,
        HostInventoryRecord $record,
        ?SyncAdapterInstance $instance,
        array $mapping,
    ): void {
        $adapterForDirection = $instance?->adapter();

        foreach (MappingTargets::FIELDS as $field) {
            $target = $mapping[$field] ?? MappingTargets::defaultTarget($field);
            if ($target === 'skip') {
                continue;
            }
            if ($adapterForDirection instanceof SyncAdapter
                && ! in_array($adapterForDirection->directionFor($field), ['pull', 'both'], true)) {
                continue;
            }
            // Skip the standard `model` slot when an extra is also
            // mapped to native:model. The extras loop is the last
            // writer for model_id, so a standard-slot write here
            // would spend a resolveModelIdByName() creating an
            // AssetModel keyed on hardwareModel that gets orphaned
            // when extras overwrites the asset's model_id. #19691.
            if ($field === 'model' && $target === 'native:model' && self::hasExtraMappedTo('native:model', $mapping)) {
                continue;
            }

            $value = self::recordValueFor($record, $field);
            self::writeToTarget($asset, $externalUpdates, $target, $value, $instance, $record);
        }
    }

    /**
     * Apply extra-field mappings. Extras are vendor-specific keys the
     * adapter emits into HostInventoryRecord::$extra. Valid targets
     * for extras are custom fields OR a small set of native asset
     * columns (asset_tag, notes) for admins who store per-device
     * metadata in the vendor's labels / blueprint / team field.
     * Values get stringified so array or object payloads (Fleet's
     * labels list, etc.) land as readable text regardless of the
     * underlying native / custom write path.
     *
     * Sibling of applyStandardFieldMappings but doesn't take
     * $externalUpdates because extras only route to native columns
     * or custom fields, never to the asset_external_sources side
     * table. writeToTarget (which is what feeds $externalUpdates) is
     * not on the code path here.
     *
     * @param  array<string, string>  $mapping
     */
    private static function applyExtraFieldMappings(
        Asset $asset,
        HostInventoryRecord $record,
        ?SyncAdapterInstance $instance,
        array $mapping,
    ): void {
        if ($instance === null) {
            return;
        }
        $adapter = $instance->adapter();
        if (! $adapter instanceof SyncAdapter) {
            return;
        }

        $extraFields = $adapter->extraFields();
        foreach (array_keys($extraFields) as $extraKey) {
            $target = $mapping[$extraKey] ?? 'skip';
            $value = self::stringifyExtra(
                $record->extra[$extraKey] ?? null,
                self::extraFieldType($extraFields, $extraKey),
            );
            self::writeExtraValueToTarget($asset, $target, $value, $instance, $record);
        }
    }

    /**
     * Route one extra value to its configured target. Extras only
     * write to native:{column} or custom:{id} slots. Skip and any
     * other target shape are no-ops. Null values (missing from the
     * vendor payload or unstringifiable) pass through silently so
     * partially-populated payloads never blank existing data.
     */
    private static function writeExtraValueToTarget(
        Asset $asset,
        string $target,
        ?string $value,
        SyncAdapterInstance $instance,
        ?HostInventoryRecord $record = null,
    ): void {
        if ($target === 'skip' || $value === null) {
            return;
        }

        if (str_starts_with($target, 'custom:')) {
            self::writeCustom($asset, (int) substr($target, 7), $value);

            return;
        }

        if (str_starts_with($target, 'native:')) {
            self::writeNative($asset, substr($target, 7), $value, $instance, $record);
        }
    }

    /**
     * Diff external-source column writes against a pre-sync snapshot
     * and log meaningful changes as an Actionlog. Skips heartbeat-only
     * diffs unless the adapter has heartbeat logging turned on.
     *
     * @param  array<string, mixed>  $previousExternal
     * @param  array<string, mixed>  $externalUpdates
     */
    private static function logExternalSourceChanges(
        Asset $asset,
        array $previousExternal,
        array $externalUpdates,
        bool $wasDirty,
        ?SyncAdapterInstance $instance,
    ): void {
        $externalDiff = self::diffExternal($previousExternal, $externalUpdates);
        $meaningfulExternalChange = count(array_diff(array_keys($externalDiff), ['last_seen'])) > 0;
        $heartbeatOnly = $externalDiff !== [] && ! $meaningfulExternalChange;

        $logsHeartbeats = false;
        if ($instance !== null) {
            $adapter = $instance->adapter();
            if ($adapter instanceof SyncAdapter) {
                $logsHeartbeats = $adapter->logsHeartbeats();
            }
        }

        if (! $meaningfulExternalChange && ! ($heartbeatOnly && $logsHeartbeats)) {
            return;
        }

        self::writeExternalSourceActionlog($asset, $externalDiff);
        // Bump updated_at so "recently updated" sorts reflect the
        // sync activity. Use saveQuietly so AssetObserver::updating
        // doesn't fire and log a redundant `update` Actionlog on top
        // of the external-source row we just wrote. Skipped when the
        // asset was already dirty (native columns changed) because
        // the save above handles it.
        if (! $wasDirty) {
            $asset->updated_at = now();
            $asset->saveQuietly();
        }
    }

    /**
     * Snapshot the current inventory columns from the
     * asset_external_sources row for diffing. Returns an empty array
     * when no row exists yet (first sync on this asset from any
     * adapter). Identity columns (source, external_id, company_id,
     * asset_id, id, timestamps) are stripped so the diff only covers
     * the columns the mapping loop writes.
     *
     * @return array<string, mixed>
     */
    private static function loadExternalSourceInventory(int $assetId, string $source): array
    {
        // Filter by (asset_id, source), not asset_id alone. Multi-
        // adapter assets have one row per source and the pre-sync
        // snapshot must come from THIS adapter's row for the diff
        // to be meaningful. See issue #19880.
        $row = DB::table('asset_external_sources')
            ->where('asset_id', $assetId)
            ->where('source', $source)
            ->first();
        if ($row === null) {
            return [];
        }

        $arr = (array) $row;
        unset(
            $arr['id'],
            $arr['asset_id'],
            $arr['company_id'],
            $arr['source'],
            $arr['external_id'],
            $arr['created_at'],
            $arr['updated_at'],
        );

        return $arr;
    }

    /**
     * Which inventory columns differ between the pre-sync snapshot
     * and the just-written updates. Only diffs the columns the sync
     * actually touched. untouched columns stay stable.
     *
     * @param  array<string, mixed>  $previous
     * @param  array<string, mixed>  $updates
     * @return array<string, array{old: mixed, new: mixed}>
     */
    private static function diffExternal(array $previous, array $updates): array
    {
        $diff = [];
        foreach ($updates as $column => $newValue) {
            $oldValue = $previous[$column] ?? null;
            if ((string) $oldValue !== (string) $newValue) {
                $diff[$column] = ['old' => $oldValue, 'new' => $newValue];
            }
        }

        return $diff;
    }

    /**
     * Write an Actionlog entry describing an external-source column
     * change. Uses log_meta with the same shape AssetObserver uses on
     * native-column updates so the asset-history renderer can display
     * it uniformly. log_meta is a plain TEXT column carrying JSON-
     * encoded strings (per feedback_log_meta_column memory).
     *
     * @param  array<string, array{old: mixed, new: mixed}>  $diff
     */
    private static function writeExternalSourceActionlog(Asset $asset, array $diff): void
    {
        $log = new Actionlog;
        $log->item_id = $asset->id;
        $log->item_type = Asset::class;
        $log->created_at = now();
        $log->created_by = null; // system-driven, not a user action
        $log->log_meta = json_encode($diff);
        $log->logaction('update');
    }

    /**
     * Read all mapping.* config keys for this instance and index them
     * by normalized field name. Empty array when the instance is null
     * (asset carries a legacy source with no corresponding instance).
     *
     * @return array<string, string>
     */
    private static function loadMapping(?SyncAdapterInstance $instance): array
    {
        if ($instance === null) {
            return [];
        }

        $mapping = [];

        // Standard normalized fields.
        foreach (MappingTargets::FIELDS as $field) {
            $stored = SyncAdapterConfig::get($instance->id, 'mapping.'.$field);
            if ($stored !== null) {
                $mapping[$field] = $stored;
            }
        }

        // Adapter-specific extra fields, if the adapter declares any.
        $adapter = $instance->adapter();
        if ($adapter instanceof SyncAdapter) {
            foreach (array_keys($adapter->extraFields()) as $extraKey) {
                $stored = SyncAdapterConfig::get($instance->id, 'mapping.'.$extraKey);
                if ($stored !== null) {
                    $mapping[$extraKey] = $stored;
                }
            }
        }

        return $mapping;
    }

    /**
     * Convert an extra-field value from the vendor's payload into a
     * string suitable for a custom field. Boolean-typed extras render
     * to '1' or '0' so a checkbox custom field's stored value matches
     * what its UI expects. Scalars pass through. Arrays of scalars
     * get comma-joined so a list like Fleet's labels lands as
     * "server, prod, us-east". Everything else falls back to JSON so
     * admins at least see the raw shape.
     */
    private static function stringifyExtra(mixed $value, string $type = 'text'): ?string
    {
        if ($value === null) {
            return null;
        }

        if ($type === 'boolean') {
            return ((bool) $value) ? '1' : '0';
        }

        if (is_scalar($value)) {
            return (string) $value;
        }

        if (is_array($value)) {
            $allScalar = array_reduce(
                $value,
                fn ($carry, $v) => $carry && is_scalar($v),
                true,
            );

            return $allScalar
                ? implode(', ', array_map(fn ($v) => (string) $v, $value))
                : json_encode($value);
        }

        return json_encode($value);
    }

    /**
     * Extract the type of an extra field from an adapter's
     * extraFields() declaration. Entries can be either plain strings
     * (defaults to text) or arrays with an explicit `type` value
     * ('text', 'boolean'). label_key vs label doesn't matter here;
     * this helper only reads the type slot.
     *
     * @param  array<string, string|array{label?: string, label_key?: string, type?: string, admin_defined?: bool}>  $extraFields
     */
    private static function extraFieldType(array $extraFields, string $key): string
    {
        $entry = $extraFields[$key] ?? null;
        if (is_array($entry) && isset($entry['type'])) {
            return $entry['type'];
        }

        return 'text';
    }

    /**
     * Create the minimum viable Asset row so we have an id to hang
     * downstream mapping writes off. Uses a synthetic name (source
     * slug + external id) since the hostname mapping may point at a
     * custom field or be skipped entirely. The mapping loop overwrites
     * asset.name if the hostname mapping is native:name.
     *
     * When the instance is scoped to a company, new assets inherit its
     * company_id so FMCS-scoped views only see their own company's
     * synced hosts.
     */
    /**
     * @param  array<string, string>  $mapping
     */
    private static function createShellAsset(HostInventoryRecord $record, ?SyncAdapterInstance $instance, array $mapping = []): Asset
    {
        $asset = new Asset;
        $asset->name = $record->sourceKey.'-'.$record->sourceId;
        $asset->model_id = self::resolveModelId($record, $instance, $mapping);
        $asset->status_id = self::resolveStatusId($instance);
        $asset->asset_tag = self::resolveAssetTag($record, $instance);
        $asset->company_id = self::resolveCompanyId($record, $instance);
        // Set serial before save because Asset::save() adds a `required`
        // rule to the serial field when the resolved model has
        // require_serial = 1.
        $asset->serial = $record->hardwareSerial;
        // Asset uses ValidatingTrait, so save() returns false on
        // validation failure without throwing. Without this guard the
        // caller then wrote asset_external_sources with asset_id=null
        // and only surfaced the FK violation, hiding the real cause
        // (e.g. model_id is null because the adapter's model mapping
        // points at a field the vendor didn't return, or asset_tag
        // collided with an existing row). Raise the validation errors
        // so the sync loop's catch block logs the actionable message.
        if (! $asset->save()) {
            throw new RuntimeException(sprintf(
                'could not save asset for %s record %s: %s',
                $record->sourceKey,
                $record->sourceId,
                implode('; ', $asset->getErrors()->all()) ?: 'unknown validation failure',
            ));
        }

        return $asset;
    }

    /**
     * Status label id for newly-created assets. Precedence:
     *   1. Adapter's configured default_status_id (when set and the
     *      referenced label still exists).
     *   2. First deployable status label.
     *   3. First status label of any kind.
     * Throws if the tenant has no status labels at all, since Asset
     * requires status_id to be set.
     */
    private static function resolveStatusId(?SyncAdapterInstance $instance): int
    {
        if ($instance !== null) {
            $adapter = $instance->adapter();
            if ($adapter instanceof SyncAdapter) {
                $configuredId = $adapter->defaultStatusId();
                if ($configuredId !== null && Statuslabel::whereKey($configuredId)->exists()) {
                    return $configuredId;
                }
            }
        }

        $status = Statuslabel::deployable()->first() ?? Statuslabel::first();
        if ($status === null) {
            throw new RuntimeException('No status label available for auto-created host inventory assets.');
        }

        return $status->id;
    }

    /**
     * Pick the Snipe-IT company id for a newly-created asset.
     * Precedence:
     *   1. Adapter's per-group company mapping (when adapter supports
     *      group scoping AND record has a vendorGroupId AND the group
     *      is mapped).
     *   2. Instance's own company_id (existing behavior).
     *   3. Null (asset lands in the shared/no-company bucket).
     *
     * Group mappings let one adapter instance sync devices from a
     * multi-tenant vendor (Kandji, Fleet, Jamf) into per-customer
     * Snipe-IT companies without needing one adapter instance per
     * company. See SyncAdapter::groupMappings().
     */
    private static function resolveCompanyId(HostInventoryRecord $record, ?SyncAdapterInstance $instance): ?int
    {
        if ($instance !== null && $record->vendorGroupId !== null && $record->vendorGroupId !== '') {
            $adapter = $instance->adapter();
            if ($adapter instanceof SyncAdapter && $adapter->supportsGroupScoping()) {
                $mapped = $adapter->companyForVendorGroup($record->vendorGroupId);
                if ($mapped !== null) {
                    return $mapped;
                }
            }
        }

        return $instance?->company_id;
    }

    /**
     * Pick the asset tag for a newly-created asset. Precedence:
     *   1. Adapter's configured pattern (with placeholders substituted).
     *   2. Snipe-IT's global autoincrement setting.
     *   3. Fallback synthetic tag (source-external_id) so save never
     *      lands with a null tag even when the other two miss.
     *
     * The pattern lets admins force a stable per-vendor tag scheme
     * (KANDJI-{serial}, FLEET-{external_id}, etc.) so re-imported
     * assets keep their tag across reinstalls. See SyncAdapter
     * -> assetTagPattern() for the storage side.
     */
    private static function resolveAssetTag(HostInventoryRecord $record, ?SyncAdapterInstance $instance): string
    {
        $adapter = $instance?->adapter();
        if ($adapter instanceof SyncAdapter) {
            $pattern = $adapter->assetTagPattern();
            if ($pattern !== null) {
                $rendered = self::renderAssetTagPattern($pattern, $record);
                if ($rendered !== null && $rendered !== '') {
                    return $rendered;
                }
            }
        }

        return Asset::autoincrement_asset()
            ?: $record->sourceKey.'-'.$record->sourceId;
    }

    /**
     * Substitute the known placeholders in an asset-tag pattern with
     * values from the record. Unknown / unpopulated placeholders
     * render as empty. Returns the trimmed result, or null when the
     * pattern rendered to an empty string entirely (which triggers
     * the caller's autoincrement fallback).
     *
     * Placeholders supported today: {serial} {external_id} {hostname}
     * {model} {source}. Extras (e.g. {extra.kandji_asset_tag}) can be
     * added later without touching callers.
     */
    /**
     * Recognized placeholder tokens for asset_tag_pattern. Kept as a
     * public constant so the validation rule (AssetTagPatternRule)
     * can reference the same list without drifting from the
     * substitution logic below.
     */
    public const ASSET_TAG_PATTERN_PLACEHOLDERS = [
        '{serial}',
        '{external_id}',
        '{hostname}',
        '{model}',
        '{source}',
    ];

    private static function renderAssetTagPattern(string $pattern, HostInventoryRecord $record): ?string
    {
        $substitutions = [
            '{serial}' => (string) ($record->hardwareSerial ?? ''),
            '{external_id}' => $record->sourceId,
            '{hostname}' => (string) ($record->hostname ?? ''),
            '{model}' => (string) ($record->hardwareModel ?? ''),
            '{source}' => $record->sourceKey,
        ];

        $rendered = trim(strtr($pattern, $substitutions));

        return $rendered === '' ? null : $rendered;
    }

    /**
     * Extract the normalized value for a given field from the record.
     *
     * `last_seen` passes through a timezone rotation to app.timezone before
     * the naive string is produced. Vendor adapters typically parse their
     * API response with `Carbon::parse` on an ISO-8601 string carrying a
     * `Z` suffix, which yields a Carbon in UTC. `toDateTimeString()` on
     * that instance would write UTC wall clock into a column every other
     * Snipe-IT write populates with app-timezone wall clock, and the view
     * layer would then interpret that UTC wall clock as if it were in
     * app.timezone (future-dated on anything west of UTC, past-dated on
     * anything east).
     *
     * This is part of a much bigger yuck that we'll eventually have to solve
     * with a fugly migration and then putting everything into UTC properly.
     * For now, this is a stopgap to keep the sync from writing
     * future-dated last_seen values, so while it's still "wrong", it's at
     * least "wrong in the same way as everything else" and doesn't
     * break the view layer.
     *
     * Laravel pulled APP_TIMEZONE out of the config in 10.x but still
     * honors it in 11.x, so this is a workaround until we can get a proper
     * fix in place. See #19765.
     */
    private static function recordValueFor(HostInventoryRecord $record, string $field): mixed
    {
        return match ($field) {
            'hostname' => $record->hostname,
            'serial' => $record->hardwareSerial,
            'asset_tag' => $record->assetTag,
            'model' => $record->hardwareModel,
            'mac' => $record->primaryMac,
            'ip' => $record->primaryIp,
            'os' => $record->os,
            'os_version' => $record->osVersion,
            'last_seen' => $record->lastSeen?->copy()->timezone(config('app.timezone'))->toDateTimeString(),
            default => null,
        };
    }

    /**
     * Route a single (field, target, value) triple. Native writes go
     * on the Asset instance (saved together at the end of the run).
     * External-source column writes gather into a batch. Custom
     * field writes hit the asset's dynamic column via the model's
     * standard attribute magic.
     *
     * @param  array<string, mixed>  $externalUpdates  passed by reference
     */
    private static function writeToTarget(Asset $asset, array &$externalUpdates, string $target, mixed $value, ?SyncAdapterInstance $instance = null, ?HostInventoryRecord $record = null): void
    {
        if ($value === null && $target !== 'native:model') {
            // Nothing to write. Skip so we don't blank existing data on
            // partial syncs.
            return;
        }

        [$type, $id] = array_pad(explode(':', $target, 2), 2, '');

        switch ($type) {
            case 'native':
                self::writeNative($asset, $id, $value, $instance, $record);
                break;
            case 'external':
                // Normalized field names get translated to actual
                // side-table column names here. Keeps the target
                // encoding symmetric with MappingTargets::FIELDS
                // rather than leaking `primary_` schema naming into
                // the target strings and translation keys.
                $column = match ($id) {
                    'mac' => 'primary_mac',
                    'ip' => 'primary_ip',
                    default => $id,
                };
                $externalUpdates[$column] = $value;
                break;
            case 'custom':
                self::writeCustom($asset, (int) $id, $value);
                break;
        }
    }

    private static function writeNative(Asset $asset, string $column, mixed $value, ?SyncAdapterInstance $instance = null, ?HostInventoryRecord $record = null): void
    {
        switch ($column) {
            case 'name':
                if ($value !== null && $value !== '') {
                    $asset->name = $value;
                }
                break;
            case 'serial':
                $asset->serial = $value;
                break;
            case 'asset_tag':
                // Only overwrite when the vendor sent a non-empty tag,
                // so a sync run that happens to omit the tag doesn't
                // blank whatever the admin already curated.
                $tag = is_string($value) ? trim($value) : $value;
                if ($tag !== null && $tag !== '') {
                    $asset->asset_tag = $tag;
                }
                break;
            case 'notes':
                // Same non-empty guard as asset_tag, with the same
                // whitespace-only coercion.
                $notes = is_string($value) ? trim($value) : $value;
                if ($notes !== null && $notes !== '') {
                    $asset->notes = $notes;
                }
                break;
            case 'model':
                // Model comes as a string name. Resolve or auto-create,
                // routing to a per-record category when the adapter
                // provides one (e.g. ABM productFamily) and falling
                // back to the instance-wide default_category_id.
                if ($value !== null && $value !== '') {
                    $asset->model_id = self::resolveModelIdByName((string) $value, $instance, $record);
                }
                break;
            case 'byod':
                // Boolean extras arrive here stringified to '1' or '0'
                // by stringifyExtra(). Convert back to the model's
                // boolean shape so the column stores the right type.
                // Empty string means the vendor didn't send a value on
                // this sync cycle, so skip rather than false-blank.
                if ($value !== null && $value !== '') {
                    $asset->byod = ($value === '1');
                }
                break;
            case 'purchase_date':
                // Watson validating rule wants date_format:Y-m-d.
                // Log + skip if the string isn't parseable so a bad record
                // doesn't donk the sync run.
                //
                // Rotate to app.timezone before extracting the date part so
                // a vendor datetime at the UTC day boundary (e.g.
                // "2024-07-23T03:00:00Z" which is 2024-07-22 20:00 Pacific)
                // records the date the user would recognize. Same reason
                // the last_seen path converts to app timezone before
                // producing its naive string. #19765.
                if ($value !== null && $value !== '') {
                    try {
                        $asset->purchase_date = \Carbon\Carbon::parse((string) $value)->timezone(config('app.timezone'))->format('Y-m-d');
                    } catch (\Exception $e) {
                        Log::channel('sync-adapters')->warning("Skipping unparseable purchase_date \"{$value}\" for asset {$asset->id}: ".$e->getMessage());
                    }
                }
                break;
            case 'order_number':
                if ($value !== null && $value !== '') {
                    $asset->order_number = (string) $value;
                }
                break;
            case 'eol_date':
                // Vendor-sourced EOL. Set eol_explicit so the Asset
                // eolDate accessor honors this value over the derived
                // "purchase_date + model.eol months" default.
                if ($value !== null && $value !== '') {
                    try {
                        $asset->asset_eol_date = \Carbon\Carbon::parse((string) $value)->timezone(config('app.timezone'))->format('Y-m-d');
                        $asset->eol_explicit = true;
                    } catch (\Exception $e) {
                        Log::channel('sync-adapters')->warning("Skipping unparseable eol_date \"{$value}\" for asset {$asset->id}: ".$e->getMessage());
                    }
                }
                break;
            case 'model_number':
                // Writes to the resolved AssetModel row, not the asset.
                $modelNumber = is_string($value) ? trim($value) : $value;
                if ($modelNumber === null || $modelNumber === '' || $asset->model_id === null) {
                    break;
                }
                $assetModel = AssetModel::find($asset->model_id);
                if ($assetModel === null) {
                    break;
                }
                if ($assetModel->model_number === $modelNumber) {
                    break;
                }
                $assetModel->model_number = $modelNumber;
                try {
                    $assetModel->save();
                } catch (\Exception $e) {
                    Log::channel('sync-adapters')->warning("Skipping model_number update \"{$modelNumber}\" for AssetModel {$assetModel->id}: ".$e->getMessage());
                }
                break;
        }
    }

    private static function writeCustom(Asset $asset, int $customFieldId, mixed $value): void
    {
        $field = CustomField::find($customFieldId);
        if ($field === null || $field->db_column === null) {
            return;
        }

        // #19725: a boolean extra with a false value arrives here as
        // the string '0' via stringifyExtra(). Single-option checkbox
        // custom fields (option list = ['1']) reject '0' through the
        // `checkboxes` validator and blow up the whole asset save with
        // "contains invalid options", so nothing on that device syncs.
        // Empty string is what an unchecked checkbox stores natively
        // and passes validation cleanly, so translate here. Checkbox
        // fields that DO list '0' as a valid option (a two-option
        // "on/off" setup) still get the raw '0' passed through.
        if ($field->element === 'checkbox' && $value === '0') {
            $options = $field->formatFieldValuesAsArray();
            if (! in_array('0', $options, true)) {
                $value = '';
            }
        }

        $asset->{$field->db_column} = $value;
    }

    /**
     * Detect the "sync only changed the last_seen custom field" case
     *
     * @param  array<string, string>  $mapping
     */
    private static function isHeartbeatOnlyAssetDirty(
        Asset $asset,
        array $mapping,
        ?SyncAdapterInstance $instance,
    ): bool {
        if (! $asset->isDirty()) {
            return false;
        }
        if ($instance === null) {
            return false;
        }
        $adapter = $instance->adapter();
        if (! $adapter instanceof SyncAdapter || $adapter->logsHeartbeats()) {
            return false;
        }

        $lastSeenTarget = $mapping['last_seen'] ?? MappingTargets::defaultTarget('last_seen');
        if (! str_starts_with($lastSeenTarget, 'custom:')) {
            return false;
        }

        $field = CustomField::find((int) substr($lastSeenTarget, 7));
        if ($field === null || $field->db_column === null) {
            return false;
        }

        return array_keys($asset->getDirty()) === [$field->db_column];
    }

    /**
     * Write the inventory columns onto the asset's external-source
     * row for this specific adapter. The identity columns (source,
     * external_id, company_id) are already written at create time and
     * never change here. updateOrInsert covers the edge case where the
     * identity row was somehow deleted between the create step and
     * this write.
     *
     * Match key is (asset_id, source) because an asset synced by two
     * adapters has two rows in asset_external_sources, one per source.
     * Keying on asset_id alone would overwrite whichever row MySQL
     * returned first regardless of adapter. See issue #19880.
     */
    private static function upsertExternalSource(Asset $asset, string $source, array $updates): void
    {
        DB::table('asset_external_sources')->updateOrInsert(
            ['asset_id' => $asset->id, 'source' => $source],
            $updates + ['updated_at' => now()],
        );
    }

    /**
     * Look up an AssetModel by the record's hardware_model string,
     * auto-create if missing. When the vendor sends no hardware_model
     * (osquery sometimes omits it, some MDMs return null for VMs),
     * return null so the caller / Asset validation ("model_id" is
     * required in Asset::$rules) refuses the save. That leaves the
     * host out of Snipe-IT rather than piling nameless assets into
     * an "Unknown" bucket admins can't clean up later.
     *
     * Auto-created models get hung off a "Discovered Hardware"
     * category which is itself get-or-created.
     */
    /**
     * @param  array<string, string>  $mapping
     */
    private static function resolveModelId(HostInventoryRecord $record, ?SyncAdapterInstance $instance = null, array $mapping = []): ?int
    {
        $modelSource = self::resolveModelSourceValue($record, $mapping);
        if ($modelSource === null || $modelSource === '') {
            return null;
        }

        return self::resolveModelIdByName($modelSource, $instance, $record);
    }

    /**
     * True when at least one extra-field mapping targets the given
     * mapping target string (typically 'native:model'). Used to
     * suppress the standard-field write when an extra is going to
     * overwrite the same target further down the mapping loop.
     *
     * @param  array<string, string>  $mapping
     */
    private static function hasExtraMappedTo(string $target, array $mapping): bool
    {
        foreach ($mapping as $key => $mappedTarget) {
            if ($mappedTarget !== $target) {
                continue;
            }
            if (in_array($key, MappingTargets::FIELDS, true)) {
                continue;
            }

            return true;
        }

        return false;
    }

    /**
     * Pick the value that will end up as this asset's AssetModel name
     * once the mapping loop finishes. When an admin has routed an extra
     * to native:model (Apple Business Manager's marketing name is the
     * common case), the extras loop is the last writer for model_id.
     * createShellAsset must use the same source so the auto-created
     * AssetModel matches what the mapping loop would settle on. Falls
     * back to the record's hardwareModel when nothing is remapped to
     * native:model. Fixes #19691: a phantom AssetModel named after the
     * vendor's part number was left dangling on every new asset when
     * the marketing name was mapped in.
     *
     * @param  array<string, string>  $mapping
     */
    private static function resolveModelSourceValue(HostInventoryRecord $record, array $mapping): ?string
    {
        foreach ($mapping as $key => $target) {
            if ($target !== 'native:model') {
                continue;
            }
            if (in_array($key, MappingTargets::FIELDS, true)) {
                // Standard field slot. Its source is hardwareModel,
                // which is the same value the fallback below returns.
                continue;
            }
            $value = $record->extra[$key] ?? null;
            if ($value !== null && $value !== '') {
                return (string) $value;
            }
        }

        return $record->hardwareModel;
    }

    private static function resolveModelIdByName(string $modelName, ?SyncAdapterInstance $instance = null, ?HostInventoryRecord $record = null): int
    {
        $canonicalModelNumber = $record?->canonicalModelNumber;
        $canonicalMarketingName = $record?->canonicalMarketingName;

        // When AppleDB enrichment updated
        // canonical values on the model record, consolidate rows across
        // adapters that emit the same hardware under different
        // vendor name strings (e.g. ABM's long marketing name vs.
        // Fleet's short osquery name for the same productType).
        // Primary clause finds-by-name-and-number. Fallback clause
        // picks up rows a prior sync named differently but tagged
        // with the same canonical marketing name.
        if ($canonicalModelNumber !== null) {
            $query = AssetModel::query()
                ->where('model_number', $canonicalModelNumber)
                ->where(function ($q) use ($modelName, $canonicalMarketingName) {
                    $q->where('name', $modelName);
                    if ($canonicalMarketingName !== null) {
                        $q->orWhere('mfg_marketing_name', $canonicalMarketingName);
                    }
                });

            $model = $query->first();
            if ($model !== null) {
                $perRecordId = self::perRecordCategoryId($instance, $record);
                if ($perRecordId !== null && $model->category_id !== $perRecordId) {
                    $model->category_id = $perRecordId;
                    $model->save();
                }

                return $model->id;
            }
        }

        $model = AssetModel::where('name', $modelName)->first();
        if ($model !== null) {
            // Re-sync the category ONLY when the adapter has a
            // per-record opinion (e.g. ABM's productFamily +
            // deviceModel routing). Falling through to
            // default_category_id doesn't touch the existing
            // category, because admins often curate model categories
            // by hand and the instance-wide default would clobber
            // that work every sync.
            $perRecordId = self::perRecordCategoryId($instance, $record);
            if ($perRecordId !== null && $model->category_id !== $perRecordId) {
                $model->category_id = $perRecordId;
                $model->save();
            }

            return $model->id;
        }

        $model = new AssetModel;
        $model->name = $modelName;
        $model->category_id = self::categoryIdFor($instance, $record);
        $model->manufacturer_id = self::manufacturerIdFor($record);
        if ($canonicalModelNumber !== null) {
            $model->model_number = $canonicalModelNumber;
        }
        if ($canonicalMarketingName !== null) {
            $model->mfg_marketing_name = $canonicalMarketingName;
        }
        $adapter = $instance?->adapter();
        if ($adapter instanceof SyncAdapter) {
            $model->fieldset_id = $adapter->defaultFieldsetId();
        }
        $model->save();

        return $model->id;
    }

    /**
     * Resolve the manufacturer for a new model. MySQL's default
     * collation is case-insensitive, so firstOrCreate matches 'apple'
     * or 'APPLE' to an existing 'Apple' row without a duplicate. When
     * we do create a new one, log a warning so admins can spot near-
     * duplicates like 'Apple' vs 'Apple, Inc.' that the collation
     * won't catch. Returns null when the record carries no
     * manufacturer so we don't stamp a default.
     */
    private static function manufacturerIdFor(?HostInventoryRecord $record): ?int
    {
        $name = $record?->manufacturer;
        if (! is_string($name) || trim($name) === '') {
            return null;
        }

        $manufacturer = Manufacturer::firstOrCreate(['name' => trim($name)]);
        if ($manufacturer->wasRecentlyCreated) {
            Log::channel('sync-adapters')->warning(
                "Sync adapter created new manufacturer \"{$manufacturer->name}\". If this duplicates an existing manufacturer under a different spelling, reassign the affected asset models to the manufacturer you want to keep and delete the extra one.",
            );
        }

        return (int) $manufacturer->id;
    }

    /**
     * Category id auto-created models get hung off. Precedence:
     *   1. Adapter's per-record override (e.g. ABM productFamily
     *      routing to family-specific categories) via
     *      categoryIdForRecord($record).
     *   2. Adapter's instance-wide default_category_id.
     *   3. Get-or-create "Discovered Hardware" fallback so we always
     *      produce a valid category_id (AssetModel requires one).
     */
    private static function categoryIdFor(?SyncAdapterInstance $instance, ?HostInventoryRecord $record = null): int
    {
        $perRecordId = self::perRecordCategoryId($instance, $record);
        if ($perRecordId !== null) {
            return $perRecordId;
        }

        if ($instance !== null) {
            $adapter = $instance->adapter();
            if ($adapter instanceof SyncAdapter) {
                $configuredId = $adapter->defaultCategoryId();
                if ($configuredId !== null && Category::whereKey($configuredId)->exists()) {
                    return $configuredId;
                }
            }
        }

        return Category::firstOrCreate(
            ['name' => 'Discovered Hardware', 'category_type' => 'asset'],
        )->id;
    }

    /**
     * Adapter-declared per-record category id, validated to still
     * exist. Returns null when the adapter has no per-record opinion
     * OR the id it returned no longer resolves (e.g. an admin
     * deleted the target category after configuring the override).
     * Null return means "no explicit re-sync intent" and callers
     * should fall through to their own defaults.
     */
    private static function perRecordCategoryId(?SyncAdapterInstance $instance, ?HostInventoryRecord $record): ?int
    {
        if ($instance === null || $record === null) {
            return null;
        }
        $adapter = $instance->adapter();
        if (! $adapter instanceof SyncAdapter) {
            return null;
        }
        $id = $adapter->categoryIdForRecord($record);
        if ($id === null || ! Category::whereKey($id)->exists()) {
            return null;
        }

        return $id;
    }

    /**
     * Look up the vendor-reported user on the record against Snipe-IT
     * users per the adapter's configured match strategy, and assign
     * the asset when the lookup succeeds. Never un-assigns: a payload
     * missing the user field leaves the existing assignment intact.
     */
    private static function assignUserIfMatched(Asset $asset, HostInventoryRecord $record, ?SyncAdapterInstance $instance): void
    {
        if ($instance === null) {
            return;
        }

        $adapter = $instance->adapter();
        if (! $adapter instanceof SyncAdapter) {
            return;
        }

        $strategy = $adapter->userMatchStrategy();
        if ($strategy === 'none') {
            return;
        }

        $attempts = self::buildUserMatchAttempts($record, $strategy);

        if ($attempts === []) {
            if ($adapter->checksInOnNullUser()
                && $asset->assigned_to !== null
                && $asset->assigned_type === User::class) {
                self::silentCheckinAsset($asset, $instance);
            }

            return;
        }

        $user = self::resolveUserFromAttempts($attempts, $instance, $strategy, $record->sourceId);
        if ($user === null) {
            return;
        }

        self::applyUserAssignment($asset, $user, $adapter, $instance);
    }

    /**
     * Build the ordered list of (field, value) attempts for the user-
     * match strategy. Cascade strategy tries username first (guaranteed
     * unique in Snipe-IT) then email as fallback. Explicit single-field
     * strategies produce one attempt. Attempts where the vendor gave us
     * nothing to match on are filtered out so callers can distinguish
     * "vendor reported no user at all" (opt-in checkin-on-null) from
     * "vendor gave us a user we couldn't find" (warning log).
     *
     * @return array<int, array{0: string, 1: string}>
     */
    private static function buildUserMatchAttempts(HostInventoryRecord $record, string $strategy): array
    {
        $attempts = match ($strategy) {
            'email' => [['email', $record->assignedUserEmail]],
            'username' => [['username', $record->assignedUserName]],
            'username_then_email' => [
                ['username', $record->assignedUserName],
                ['email', $record->assignedUserEmail],
            ],
            default => [],
        };

        return array_values(array_filter(
            $attempts,
            fn (array $a) => is_string($a[1]) && $a[1] !== '',
        ));
    }

    /**
     * Walk the ordered attempts and return the first matching user.
     * Emits an info log on success and a warning on complete miss so
     * admins can see the strategy played out per-host. Returns null
     * when no attempt matched.
     *
     * @param  array<int, array{0: string, 1: string}>  $attempts
     */
    private static function resolveUserFromAttempts(
        array $attempts,
        SyncAdapterInstance $instance,
        string $strategy,
        string $sourceId,
    ): ?User {
        foreach ($attempts as [$field, $value]) {
            $candidate = User::query()->where($field, $value)->first();
            if ($candidate !== null) {
                Log::channel('sync-adapters')->info(sprintf(
                    '%s sync: matched user via %s=%s for host %s',
                    $instance->slug,
                    $field,
                    $value,
                    $sourceId,
                ));

                return $candidate;
            }
        }

        $tried = implode(', ', array_map(
            fn (array $a) => sprintf('%s=%s', $a[0], $a[1]),
            $attempts,
        ));
        Log::channel('sync-adapters')->warning(sprintf(
            '%s sync: no Snipe-IT user matched (strategy=%s, tried [%s]) for host %s',
            $instance->slug,
            $strategy,
            $tried,
            $sourceId,
        ));

        return null;
    }

    /**
     * Commit the assignment. Suppress mode is always silent (direct
     * assignment). Otherwise fall through to Asset::checkOut() which
     * fires the CheckoutableCheckedOut event and its notification
     * listener. The event constructor requires a non-null admin User.
     * auth() is null for CLI-triggered sync runs, so silently fall
     * back to direct assignment when there's no auth context to
     * attach the event to. Skips when the asset is already assigned
     * to the resolved user.
     */
    private static function applyUserAssignment(
        Asset $asset,
        User $user,
        SyncAdapter $adapter,
        SyncAdapterInstance $instance,
    ): void {
        if ((int) $asset->assigned_to === (int) $user->id
            && $asset->assigned_type === User::class) {
            return;
        }

        $admin = auth()->user();
        if ($adapter->suppressesNotifications() || $admin === null) {
            self::silentAssignToUser($asset, $user);

            return;
        }

        $asset->checkOut(
            target: $user,
            admin: $admin,
            checkout_at: now()->toDateTimeString(),
            note: 'Assigned via sync from '.$instance->slug,
            name: $asset->name,
        );
    }

    /**
     * Direct assignment that skips the CheckoutableCheckedOut event
     * (and therefore the checkout-email listener). Used when the
     * adapter has suppress_notifications on. Still writes an
     * Actionlog entry so the asset's history reflects the assignment.
     */
    private static function silentAssignToUser(Asset $asset, User $user): void
    {
        $asset->assigned_to = $user->id;
        $asset->assigned_type = User::class;
        $asset->last_checkout = now();
        if ($user->location_id !== null) {
            $asset->location_id = $user->location_id;
        }
        // See #19726 note above the primary write site. saveOrFail()
        // returns false rather than throwing when Asset's fieldset
        // validation aborts the save, so we check save()'s return
        // and raise for the pull loop's catch to log.
        if (! $asset->save()) {
            $errors = implode('; ', $asset->getErrors()->all()) ?: 'unknown validation failure';
            throw new RuntimeException("could not persist sync-driven checkout on asset {$asset->id}: {$errors}");
        }

        $log = new Actionlog;
        $log->item_id = $asset->id;
        $log->item_type = Asset::class;
        $log->target_id = $user->id;
        $log->target_type = User::class;
        $log->created_at = now();
        $log->created_by = null; // system-driven
        $log->note = 'Assigned via sync';
        $log->logaction('checkout');
    }

    /**
     * Silent counterpart to silentAssignToUser: clears the assignment
     * on the asset and writes a checkin Actionlog so the asset's
     * history shows the sync-driven un-assign. Skips the standard
     * CheckoutableCheckedIn event to keep scheduled syncs from
     * blasting checkin notifications every cycle.
     */
    private static function silentCheckinAsset(Asset $asset, SyncAdapterInstance $instance): void
    {
        $previousUserId = $asset->assigned_to;
        $previousUserType = $asset->assigned_type;

        $asset->assigned_to = null;
        $asset->assigned_type = null;
        $asset->last_checkin = now();
        // See #19726 note above the primary write site.
        if (! $asset->save()) {
            $errors = implode('; ', $asset->getErrors()->all()) ?: 'unknown validation failure';
            throw new RuntimeException("could not persist sync-driven checkin on asset {$asset->id}: {$errors}");
        }

        $log = new Actionlog;
        $log->item_id = $asset->id;
        $log->item_type = Asset::class;
        $log->target_id = $previousUserId;
        $log->target_type = $previousUserType;
        $log->created_at = now();
        $log->created_by = null;
        $log->note = 'Checked in via sync from '.$instance->slug.' (vendor reported no assigned user)';
        $log->logaction('checkin from');
    }
}