Skip to main content

tenant-service — AI_INTEGRATION

Companion: APPLICATION_LOGIC §3.6 · SECURITY_MODEL · Platform: 08 AI Architecture

tenant-service is a light AI consumer. It does not host models and does not author prompts directly; it routes signals through ai-orchestrator-service and reacts to advisory results. AI never auto-mutates tenant data. Every AI-derived recommendation is advisory only and surfaces in the Activity Center for an operator to confirm or dismiss.

1. AIClient Port​

// src/application/ports/ai-client.ts
export interface AIClient {
  classifyInvite(input: { invitation: Invitation; tenantContext: TenantContext }): Promise<AdvisoryResult<InviteAbuseSignal>>;
  reviewBulkRemoval(input: { tenantId: TenantId; actor: UserId; targets: MembershipId[]; }): Promise<AdvisoryResult<BulkActionRiskSignal>>;
}

export interface AdvisoryResult<T> {
  decision: 'allow' | 'review' | 'block_recommended';
  confidence: number;                    // 0..1
  signals: T;
  provenance: AIProvenance;              // model, version, prompt id, latency, cost; see ai-orchestrator-service
  expiresAt: Date;                       // for cache stamping
}

The adapter (infrastructure/ai/orchestrator-ai-client.ts) is a thin HTTP client over ai-orchestrator-service. It enforces a circuit breaker (3 failures in 60 s opens for 60 s) and a budget guard (per-tenant monthly token cap).

2. Use Cases​

2.1 Invite Abuse Classification (advisory)​

Triggered by InviteStaff (see APPLICATION_LOGIC §3.6). The classifier scores:

  • Disposable / throwaway email domain.
  • Recent volume of invites from this tenant or actor.
  • Geolocation mismatch with billing region.
  • Domain mismatch versus registered tenant domain.

The call is non-blocking: InviteStaff returns success regardless of the AI result. If decision = 'block_recommended' and confidence ≥ 0.85, the invitation is auto-flipped to pending_review and surfaced to tenant.owner in-app; the email is not sent until manually approved. If confidence < 0.85, the invitation proceeds and the signal is logged in audit_events only.

2.2 Bulk Membership Removal Anomaly Review (advisory)​

When RemoveMembership is invoked on ≥ 5 memberships within 60 s for the same actor, the application layer fires AIClient.reviewBulkRemoval synchronously with a 200 ms timeout. If the response is block_recommended and confidence ≥ 0.9, the second-and-following removals are deferred (MELMASTOON.TENANT.BULK_ACTION_REVIEW_REQUIRED, HTTP 423) until a tenant.owner co-signs via the Backoffice "Sensitive Action" prompt.

2.3 Anomaly Stream from ai-orchestrator-service​

The orchestrator emits melmastoon.ai.anomaly.tenant_action.v1 for risky patterns it detects in the broader event stream. Tenant-service subscribes and:

  • Annotates the relevant audit_events row with the anomaly id.
  • Notifies the tenant's tenant.owner membership through notification-service (in-app + email).

The service does not auto-suspend, auto-revoke roles, or auto-cancel invitations based on anomalies. Operator action is always required.

3. Provenance, Audit, and No-Training​

Every AI call records an AIProvenance envelope inside the audit_events.before/after blob:

{
  "model": "vertex/text-bison-32k",
  "modelVersion": "2026-Q2",
  "promptId": "invite.abuse_classifier@v3",
  "latencyMs": 142,
  "tokens": { "input": 320, "output": 64 },
  "costUsd": 0.0021,
  "decision": "review",
  "confidence": 0.78,
  "decisionId": "aid_01H..."
}
  • No-training guarantee: every prompt sent to Vertex includes disable_training=true (per platform contract); tenant data is never used to fine-tune a public model.
  • Tenant-scoped budget: per-tenant monthly token quota enforced by ai-orchestrator-service; over-budget returns decision = 'allow' (fail-open) with signals = { quotaExceeded: true }.
  • Bias monitoring: ai-orchestrator-service runs a weekly audit on classifier outcomes per residency region; tenant-service does not duplicate that responsibility.

4. Human-in-the-Loop Gates​

TriggerHuman gateWhere
Invite classifier block_recommendedtenant.owner approves in Backoffice"Pending review invitations" view
Bulk removal review blockSecond tenant.owner co-sign"Sensitive action" modal
Anomaly notificationOperator dismisses or takes actionActivity Center inbox

Every gate write traces back to the decisionId returned by the AI provider, so post-hoc audit can reconstruct the chain.

5. Edge Inference​

tenant-service does not run any edge inference itself. The Electron desktop carries the offline ABAC engine (see SYNC_CONTRACT §6) which is rule-based, not ML.

6. Failure Modes​

FailureBehavior
ai-orchestrator-service 5xx / timeoutCircuit opens; decision = 'allow', confidence = 0 recorded; alert on sustained outage
AI budget exhaustedFail-open; banner in Backoffice "AI assistance temporarily unavailable"
AI returns malformed JSONLogged; treated as allow; raises MELMASTOON.AI.INVALID_RESPONSE audit row
Provenance write failureDomain operation rolls back (provenance is part of the same transaction as the audit row)

7. Out of Scope​

  • Generating or editing tenant configuration content.
  • LLM-based role suggestion (delegated to ai-orchestrator-service via a separate prompt registered at the platform level; tenant-service only displays the suggestions).
  • Translation / summarization of audit logs (handled by ai-orchestrator-service on the analytics side).