AI Config Surface
Status: Admitted, in build-out
The SDK AI config surface contract (sdk/kernel/ai-config-surface-contract.md) is admitted. It pins how app developers configure AI profiles via SDK; the developer-facing surface is in active build-out.
What This Surface Does
The AI Config Surface is the SDK boundary where an app developer binds AI profile configuration to a scope. It pairs with:
- Platform → AI Scope Identity — the
AIScopeRefidentity contract - Runtime → AI Profile Execution — the runtime-side execution + snapshot contract
The SDK side is the typed config / profile / snapshot API apps call to apply profiles, probe, and inspect snapshots.
Method Families
| Family | Purpose |
|---|---|
| Profile apply | Apply a profile to an AIScopeRef (copy-on-write into the scope's AIConfig) |
| Profile resolve | Resolve the effective AIConfig for a scope |
| Probe (static / availability / feasibility) | Validate before execution |
| Snapshot read | Read execution evidence per K-AIEXEC-003 |
Boundary
| Owns | Does NOT own |
|---|---|
| Typed config / profile / snapshot API | AIProfile portable schema definition (Desktop) |
| Scope parameter shape | AIConfig storage (Desktop kernel) |
| Probe surface for callers | LocalProfileDescriptor execution (Runtime) |
The SDK is the typed access surface. Desktop owns AIProfile schema and AIConfig storage; Runtime owns local execution.
Reader Scenario: App Applies An AI Profile
App wants to apply a profile to a mod workspace.
- App calls SDK.
aiConfig.applyProfile({ scope: { kind: 'mod', ownerId: 'com.example.notes', surfaceId: 'workspace' }, profile }). - SDK validates. Scope identity per
AIScopeRefrules. - Desktop performs profile apply. Copy-on-write into the workspace scope's
AIConfig. - Subsequent execution under the new profile.
What This Does Not Do
- It does not let apps invent scope kinds.
- It does not let apps materialize
AIConfigdirectly bypassing profile apply. - It does not let apps consume AIScopeRef from another scope's config as runtime fallback.