Add the API import surface for legacy migrations (contract 0.8.0)

Goal: an LLM or script can migrate an entire legacy database using only
the HTTP API - original history preserved, safely re-runnable.

- X-Import-Mode header (admin only): create/update endpoints across 15
  timestamped entity types accept original createddate/modifieddate;
  helper exposed via shopdb.api (contract 0.7.0 -> 0.8.0).
- Exact-match natural-key lookup filters on 13 list endpoints for the
  lookup-then-upsert recipe.
- Selfhosted USB checkout/checkin accept backdated event times in
  import mode.
- docs/IMPORT-API.md: operator manual grounded in the real legacy
  schema - order of operations, full table-by-table mapping including
  the machines fan-out, idempotent Python importer with dry-run, parity
  checks, and decided dispositions for unmigrated tables (DNC config
  stays live-fed via the collector; supportteams/appowners map to the
  upcoming supportteams model).

635 tests pass; naming green; frontend untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/PLUGIN-HOOKS.md

@@ -9,7 +9,7 @@ The contract is locked in [ADR-001](../docs/adr/ADR-001-asset-as-platform-contra
 The framework declares its contract version in `shopdb/__init__.py`:
 
 ```python
-__contract_version__ = '0.7.0'
+__contract_version__ = '0.8.0'
 ```
 
 Each plugin's `manifest.json` declares the range of contract versions it supports:
@@ -428,7 +428,10 @@ What `shopdb.api` exposes:
 - Responses: `success_response`, `error_response`, `paginated_response`,
   `ErrorCodes`
 - Pagination: `get_pagination_params`, `paginate_query`
+- Authorization: `require_permission`, `require_role`
 - Helpers: `audit_log`, `resolve_asset_position`
+- Import mode: `apply_import_timestamps`, `import_mode_active`,
+  `parse_import_datetime`
 - Legacy employee directory: `employee_connection`
 
 ```python
@@ -479,6 +482,30 @@ position = resolve_asset_position(asset)
 
 See [ADR-001](../docs/adr/ADR-001-asset-as-platform-contract.md) for the position resolution algorithm.
 
+### Import mode (legacy timestamp passthrough)
+
+Bulk imports from the classic ASP shopdb need to preserve each row's original
+`createddate` / `modifieddate` instead of stamping "now". `apply_import_timestamps`
+does this, gated so it never affects normal traffic: it only acts when the
+caller is an admin AND sent the `X-Import-Mode: true` request header.
+
+```python
+from shopdb.api import apply_import_timestamps
+
+asset = Asset(assetnumber=data['assetnumber'], ...)
+db.session.add(asset)
+# In import mode, stamp legacy createddate/modifieddate from the payload.
+# No-op for normal callers, or when the payload omits the fields.
+apply_import_timestamps(asset, data)
+db.session.commit()
+```
+
+`import_mode_active()` returns the same admin-plus-header predicate, for guarding
+other backdated behavior (for example accepting a historical `checkouttime`).
+`parse_import_datetime(value)` parses both ISO `2020-01-05T12:00:00` and legacy
+`YYYY-MM-DD HH:MM:SS` into naive UTC. See [docs/IMPORT-API.md](IMPORT-API.md) for
+the full migration operator manual.
+
 ## Removed hooks
 
 The following hooks existed in early drafts and have been removed for v1: