209 lines
6.5 KiB
Markdown
209 lines
6.5 KiB
Markdown
# Data Model — Private AI Execution & Policy Foundation
|
|
|
|
**Spec**: [spec.md](spec.md)
|
|
|
|
No new persistent tables or AI artifact stores are required for v1. The feature reuses existing workspace settings, operational controls, and audit logs. New AI-specific structures are code-owned or request-scoped.
|
|
|
|
## Persisted Truth Reused
|
|
|
|
### Workspace AI Policy (`workspace_settings` carrier)
|
|
|
|
**Purpose**: Workspace-owned policy truth that determines whether AI is disabled entirely or limited to approved private-only use cases.
|
|
|
|
**Persisted carrier**: existing `workspace_settings` row via `WorkspaceSetting`
|
|
|
|
**Planned definition**:
|
|
- `domain`: `ai`
|
|
- `key`: `policy_mode`
|
|
- `type`: `string`
|
|
- `system_default`: `disabled`
|
|
- `allowed values`: `disabled`, `private_only`
|
|
- `scope`: workspace only; no tenant override in v1
|
|
|
|
**Validation rules**:
|
|
- required
|
|
- string
|
|
- `in:disabled,private_only`
|
|
|
|
**Authorization**:
|
|
- view: existing `workspace_settings.view`
|
|
- mutation: existing `workspace_settings.manage`
|
|
|
|
**Audit strategy**:
|
|
- reuse `workspace_setting.updated` and `workspace_setting.reset`
|
|
- include AI-specific metadata in the existing workspace-settings audit context
|
|
|
|
**State transitions**:
|
|
- `disabled` -> `private_only`
|
|
- `private_only` -> `disabled`
|
|
|
|
### AI Execution Control (`operational_control_activations` carrier)
|
|
|
|
**Purpose**: Platform-owned runtime stop for new AI execution attempts.
|
|
|
|
**Persisted carrier**: existing `OperationalControlActivation`
|
|
|
|
**Planned definition**:
|
|
- `control_key`: `ai.execution`
|
|
- `label`: `AI execution`
|
|
- `supported_scopes`: `global`
|
|
- `affected_surfaces`: governed AI decision callers only
|
|
|
|
**Behavior**:
|
|
- a matching active control blocks new AI execution decisions before provider resolution
|
|
- global pause is the required v1 incident path
|
|
- workspace-specific pause or tenant-specific pause is out of scope for v1 and remains a follow-up concern if future incident handling genuinely requires it
|
|
|
|
**State transitions**:
|
|
- `enabled` -> `paused`
|
|
- `paused` -> `enabled`
|
|
|
|
### AI Decision Audit (`audit_logs` carrier)
|
|
|
|
**Purpose**: Stable record of governed AI allow/block evaluations without storing raw prompt or output content.
|
|
|
|
**Persisted carrier**: existing `audit_logs` rows through `WorkspaceAuditLogger` / `AuditRecorder`
|
|
|
|
**Planned action strategy**:
|
|
- reuse existing workspace-setting actions for policy mutation
|
|
- add one bounded AI decision action ID, e.g. `ai_execution.decision_evaluated`, for governed decision evaluations
|
|
|
|
**Planned metadata**:
|
|
- `use_case_key`
|
|
- `decision_outcome` (`allowed` or `blocked`)
|
|
- `decision_reason`
|
|
- `workspace_ai_policy_mode`
|
|
- `requested_provider_class`
|
|
- `data_classifications`
|
|
- `source_family`
|
|
- `workspace_id`
|
|
- optional `tenant_id`
|
|
- optional `context_fingerprint`
|
|
- optional `matched_operational_control_scope`
|
|
|
|
**Explicit exclusions**:
|
|
- raw prompt text
|
|
- raw source payloads
|
|
- raw provider payloads
|
|
- full model output text
|
|
|
|
## Code-Owned Truth
|
|
|
|
### Approved AI Use Case Definition
|
|
|
|
**Purpose**: Code-owned allowlist entry that defines one approved AI purpose and its trust constraints.
|
|
|
|
**Fields**:
|
|
- `key`
|
|
- `future_consumer`
|
|
- `visibility`
|
|
- `allowed_provider_classes`
|
|
- `allowed_data_classifications`
|
|
- `source_family`
|
|
- `tenant_context_permitted`
|
|
|
|
**v1 catalog is locked to exactly two entries**:
|
|
|
|
| Key | Future Consumer | Visibility | Allowed Provider Classes | Allowed Data Classifications | Source Family | Tenant Context Permitted |
|
|
|---|---|---|---|---|---|---|
|
|
| `product_knowledge.answer_draft` | `ContextualHelpResolver` and related code-owned knowledge sources | `internal_only_draft` | `local_private` | `product_knowledge`, `operational_metadata` | `product_knowledge` | no |
|
|
| `support_diagnostics.summary_draft` | redacted summary derived from `SupportDiagnosticBundleBuilder` | `internal_only_draft` | `local_private` | `redacted_support_summary` | `support_diagnostics` | yes |
|
|
|
|
**Validation rules**:
|
|
- key must be registered in the catalog
|
|
- no third use case may appear in v1 without a spec update
|
|
- `external_public` is never allowed for these entries in v1
|
|
|
|
### Provider Class
|
|
|
|
**Purpose**: Vendor-neutral trust boundary for AI routing decisions.
|
|
|
|
**Allowed values**:
|
|
- `local_private`
|
|
- `external_public`
|
|
|
|
**Behavioral consequence**:
|
|
- `external_public` is always blocked in v1
|
|
- `local_private` may be allowed only when the use case and data classifications permit it
|
|
|
|
### AI Data Classification
|
|
|
|
**Purpose**: Declarative label that determines whether a data family may cross the governed AI boundary.
|
|
|
|
**Values**:
|
|
- `product_knowledge`
|
|
- `operational_metadata`
|
|
- `redacted_support_summary`
|
|
- `personal_data`
|
|
- `customer_confidential`
|
|
- `raw_provider_payload`
|
|
|
|
**Behavioral consequence**:
|
|
- `personal_data`, `customer_confidential`, and `raw_provider_payload` are always blocked in v1
|
|
- allowed classifications vary by use case
|
|
|
|
## Request-Scoped Contracts
|
|
|
|
### AI Execution Request
|
|
|
|
**Purpose**: In-process request envelope passed to the governed decision boundary before any provider resolution or model execution is attempted.
|
|
|
|
**Fields**:
|
|
- `workspace_id`
|
|
- optional `tenant_id`
|
|
- `actor_type`
|
|
- `actor_id`
|
|
- `use_case_key`
|
|
- `requested_provider_class`
|
|
- `data_classifications` (list)
|
|
- `source_family`
|
|
- optional `caller_surface`
|
|
- optional `context_fingerprint`
|
|
|
|
**Validation rules**:
|
|
- `workspace_id` is required
|
|
- `use_case_key` must be registered
|
|
- `requested_provider_class` must be declared by the registered use case
|
|
- every declared data classification must be allowed for the use case
|
|
- host-surface authorization must already be resolved before evaluation
|
|
|
|
**Important v1 boundary**:
|
|
- the request is a preflight contract and does not need to carry raw prompt or payload text in v1
|
|
- future runtime/provider work can extend around this envelope later, but not inside this spec
|
|
|
|
### AI Execution Decision
|
|
|
|
**Purpose**: Terminal allow/block result returned by the governed boundary.
|
|
|
|
**Fields**:
|
|
- `outcome` (`allowed` or `blocked`)
|
|
- `reason_code`
|
|
- `workspace_ai_policy_mode`
|
|
- `matched_operational_control_scope` (nullable)
|
|
- `use_case_key`
|
|
- `requested_provider_class`
|
|
- `data_classifications`
|
|
- `source_family`
|
|
- `audit_action`
|
|
- `audit_metadata`
|
|
|
|
**Behavioral consequence**:
|
|
- `blocked`: provider resolution must not occur
|
|
- `allowed`: returns an approved handoff envelope only; v1 still does not execute a provider call or create a persisted result
|
|
|
|
## State Transitions Summary
|
|
|
|
### Workspace AI Policy
|
|
|
|
- `disabled` <-> `private_only`
|
|
|
|
### Operational Control
|
|
|
|
- `enabled` <-> `paused`
|
|
|
|
### AI Execution Decision
|
|
|
|
- `evaluating` -> `allowed`
|
|
- `evaluating` -> `blocked`
|
|
|
|
There is no queued, running, retrying, completed, or persisted-result lifecycle in v1. |