AI_INTEGRATION — lock-integration-service

Bundle: SERVICE_OVERVIEW · DOMAIN_MODEL · APPLICATION_LOGIC · OBSERVABILITY · SECURITY_MODEL

Cross-cutting: docs/02 §9 AI, ai-orchestrator-service. All AI calls go through ai-orchestrator-service. This service never imports an LLM SDK.

The lock subsystem has two narrow, well-bounded AI use cases. Both are observation-only at MVP — they produce HITL Decision rows for human review, never mutate credential state autonomously. Lock-credential mutation is too physically consequential to delegate to a model.

1. AI capabilities used

Capability	Trigger	Model routing	Output	HITL?
Door-attempt anomaly scoring	Hourly batch over key_credential_attempts (last 7d) per (property, holder); also realtime stream for staff master keys	Vertex AI melmastoon-anomaly-isoforest-v1 (cloud); ONNX attempt-anomaly-edge-v1 (1.4MB) for offline-replay scoring on Electron	AnomalyScore + top-3 contributing features	Yes — score ≥ 0.85 opens a HITL Decision for the GM/security lead
Predictive battery replacement	Daily batch over lock_devices health snapshots + battery_pct deltas	Vertex AI melmastoon-battery-survival-v1 regression (cloud-only — small model, low cost)	Predicted days-to-replacement per device	No — surfaces in maintenance dashboard; auto-creates a MaintenanceTicket if predicted replacement < 7 days

Both capabilities are dispatched via ai-orchestrator-service per 02 §9.2. This service publishes the input snapshot, awaits the orchestrator's output event (or sync response on the realtime path), and persists AIProvenance on the resulting Decision row.

2. Capability 1 — Door-attempt anomaly scoring

2.1 Purpose

Detect anomalous patterns in door access events that warrant human review:

• Off-shift master-key use (staff scans during a shift they are not booked on).
• Repeated denied attempts by the same credential within a short window (possible card skimming or brute-force on PIN locks).
• Unusual geographic/temporal pattern for a guest credential (e.g., simultaneous attempts at two distant doors that exceed a walking threshold).
• Sudden spike in denied attempts at a single device (possible vendor outage masquerading as access denial; cross-correlated with device.health_alert.v1).

2.2 Trigger and dispatch

Two paths:

1. Hourly batch. Cloud Scheduler triggers ScoreAttemptBatchUseCase per tenant. The use case windows key_credential_attempts over the last 7 days per (property, credential), serializes feature vectors, and calls ai-orchestrator-service.score() with purpose: 'lock.attempt.anomaly'.
2. Realtime stream. When the rolling 1-minute denied-attempt count for a single credential exceeds 5, the inbox handler for lock.audit.attempt.v1 enqueues a synchronous score request to the orchestrator with purpose: 'lock.attempt.anomaly.realtime'. P99 latency budget for the orchestrator response: < 1500 ms; on timeout, the alert is raised without an AI score (deterministic threshold suffices).

2.3 Prompt template / model input

This is not a prompt-engineered LLM call; it is a structured-feature classifier. The orchestrator routes to the IsolationForest model via Vertex AI Model Endpoint:

{
  "model":     "melmastoon-anomaly-isoforest-v1",
  "purpose":   "lock.attempt.anomaly",
  "tenantId":  "tnt_01...",
  "features": {
    "credentialId":            "key_01...",
    "holderKind":              "staff_master",
    "denied_count_1h":         12,
    "denied_count_24h":        38,
    "granted_count_24h":       4,
    "distinct_devices_1h":     7,
    "off_shift_attempts_24h":  9,
    "since_last_granted_min":  340,
    "deny_reason_distribution": { "expired": 2, "wrong_room": 6, "other": 4 }
  }
}

2.4 Moderation policy

No safety classifier needed (no free text in/out). Privacy gate per 02 §9.4 ensures only tenantId-scoped features leave; no PII (guest name, contact) is included.

2.5 HITL flow

When AnomalyScore.confidence >= 0.85:

1. Create Decision row in ai-orchestrator-service with:
   • subject: key_credential.attempt.anomaly
   • subjectId: key_01...
   • proposedAction: none (read-only) or suspend_key_credential for high-severity (≥ 0.95)
   • evidence: anomaly score, top-3 contributing features, attempt timeline
2. Notify GM + security lead via notification-service (push + email) with deep link to the Decision in backoffice.
3. GM reviews, optionally clicks "Suspend key" — which calls POST /api/v1/key-credentials/:id/suspend with reason: 'fraud_review' and metadata.decisionId.

2.6 Edge model

For offline-replay scoring on the Electron desktop: a quantized ONNX export of the same IsolationForest is bundled at ~1.4 MB. The desktop scores newly observed attempts during offline windows; flags above threshold open a local Decision row and a desktop notification. On reconnect, both the attempts and the local decision are pushed via sync; the cloud re-scores authoritatively.

3. Capability 2 — Predictive battery replacement

3.1 Purpose

Reduce in-room failures by predicting which battery-powered locks need replacement before they go dark. Battery deaths during a guest's stay are a high-friction event in target markets where field maintenance windows are slow.

3.2 Trigger and dispatch

Daily batch (Cloud Scheduler 02:00 UTC) iterates lock_devices with battery telemetry. The use case computes per-device features:

{
  "model":     "melmastoon-battery-survival-v1",
  "purpose":   "lock.battery.predict",
  "tenantId":  "tnt_01...",
  "features": {
    "deviceId":               "lck_01...",
    "vendor":                 "ttlock",
    "current_pct":            22,
    "discharge_rate_pct_per_day": 1.7,
    "days_since_install":     412,
    "firmware":               "8.4.7",
    "ambient_avg_temp_c":     28,        // optional, when property has IoT temp sensor
    "open_cycles_30d":        184
  }
}

Output: predicted_days_to_threshold (when battery_pct will hit 5%).

3.3 Action

• predicted_days_to_threshold < 7 → publish MaintenanceTicket.create event consumed by maintenance-service; severity medium.
• predicted_days_to_threshold < 3 → also page on-call site lead via notification-service (push); severity high.
• Surfaces in the GM's "Health" desktop tab regardless.

3.4 No HITL for this capability — the predicted action (replace battery) is itself non-destructive. Maintenance tickets follow the standard workflow.

4. AIProvenance persistence

Every action triggered by an AI capability writes an AIProvenance block on the resulting artifact (Decision, MaintenanceTicket):

{
  "aiProvenance": {
    "model":          "melmastoon-anomaly-isoforest-v1",
    "modelVersion":   "2026.04.10",
    "endpoint":       "vertex:us-central1/...",
    "purpose":        "lock.attempt.anomaly",
    "promptHash":     "sha256:n/a",         // structured features path
    "featureSetHash": "sha256:abcd...",
    "scoredAt":       "2026-04-30T11:14:22Z",
    "score":          0.91,
    "topFeatures":    ["off_shift_attempts_24h","denied_count_1h","distinct_devices_1h"],
    "ruleVersion":    "lock.anomaly.v3"
  }
}

AIProvenance is mandatory; persistence attempts that omit it return MELMASTOON.AI.PROVENANCE_MISSING (422).

5. Budget and rate

Capability	Per-tenant monthly budget	Throttle
Door-attempt anomaly (batch)	30 000 inferences	100 / minute
Door-attempt anomaly (realtime)	5 000 inferences	1 / sec / credential
Battery prediction (batch)	10 000 inferences	50 / minute

Budget exhaustion returns MELMASTOON.AI.REFUSED_BUDGET (429) and the orchestrator falls back to deterministic thresholding for anomaly; battery prediction simply pauses for the day.

6. Cross-references

• 02 §9 AI — provenance, HITL, budget
• ai-orchestrator-service — model routing, safety, HITL Decision
• docs/standards/ERROR_CODES — AI