APPLE-001 — Apple Provider Authority¶

Level 1 — Authority Definition

document:
  id: APPLE-001
  title: Apple Provider Authority
  version: "1.0"
  track: platforms/apple
  updated: 2026-07
  supersedes: ~
  next_review: 2027-WWDC
authority_baseline:
  swift: "6"
  xcode: "27"
  platform_min:
    macos: "15"
    ios: "18"
    watchos: "11"
    visionos: "2"

Separation of Duties¶

Owns	Must NOT Own
Apple capability inventory, upstream ownership model, authoritative specifications, provider lifecycle, upstream drift tracking, Provider Invariant	Modernization policy (APPLE-002). Migration strategy (APPLE-002). CI rules (APPLE-003). Verification scoring (APPLE-003).

Dependencies: - APPLE-002 derives its ratchet rules from the capability ownership model defined here. - APPLE-003 computes its Provider Conformance Score from the capability registry in §2.

1. Apple as a Provider¶

Apple is a Platform Provider in the Bluefly portfolio object model.

Provider
  identity: apple
  type: platform
Products:
  SwiftUI          → owns: UI, layout, scene model, navigation, animation
  Observation      → owns: state observation, reactive binding
  Foundation       → owns: networking, data, locale, concurrency primitives
  Swift Concurrency → owns: async/await, actors, structured tasks
  Swift Testing    → owns: test authorship, assertions, parameterization
  OSLog            → owns: structured logging, signposting
  WebKit           → owns: web content rendering
  SwiftData        → owns: local relational persistence
  AppIntents       → owns: system action integration, Siri, Shortcuts
  WidgetKit        → owns: home screen and lock screen widgets
  CoreLocation     → owns: device location
  DeviceCheck / App Attest → owns: device identity verification
  WatchConnectivity → owns: Apple Watch session transport
  CarPlay          → owns: in-vehicle UI
Consumers:
  BLU Studio       → consumes Apple capabilities through published Apple APIs
  foundation-bridge → adapts Apple APIs for BLU Studio consumption

Invariant: Bluefly never reimplements a capability that Apple owns. If Apple provides it, adopt it. If Apple improves it, migrate to the improvement.

2. Capability Ownership Model¶

Every capability consumed by a Bluefly Apple product must be classified:

capability:
  id: apple.observation
  name: State Observation
  upstream_owner: Apple
  upstream_api: "@Observable / Observation framework"
  introduced: "Swift 5.9 / Xcode 15"
  current_api: "@Observable"
  superseded_api: "ObservableObject (Combine)"
  bluefly_code_required: none
  consumer: BLU Studio

capability:
  id: apple.testing
  name: Test Authorship
  upstream_owner: Apple
  upstream_api: "Swift Testing (@Test, #expect)"
  introduced: "Swift 5.10 / Xcode 16"
  current_api: "import Testing"
  superseded_api: "XCTest"
  bluefly_code_required: none
  consumer: BLU Studio

capability:
  id: apple.navigation
  name: Navigation
  upstream_owner: Apple
  upstream_api: "NavigationSplitView, NavigationStack"
  introduced: "SwiftUI (iOS 16 / macOS 13)"
  current_api: "NavigationSplitView + NavigationStack"
  superseded_api: "NavigationView"
  bluefly_code_required: none
  consumer: BLU Studio

capability:
  id: apple.concurrency
  name: Concurrency Isolation
  upstream_owner: Apple
  upstream_api: "actor, async/await, structured concurrency"
  introduced: "Swift 5.5"
  current_api: "actor"
  superseded_api: "@unchecked Sendable suppression"
  bluefly_code_required: none
  consumer: BLU Studio

capability:
  id: apple.logging
  name: Structured Logging
  upstream_owner: Apple
  upstream_api: "OSLog (Logger)"
  current_api: "Logger(subsystem:category:)"
  bluefly_code_required: thin wrapper (AppLogger)
  consumer: BLU Studio

capability:
  id: apple.web_rendering
  name: Web Content Rendering
  upstream_owner: Apple
  upstream_api: "WKWebView via NSViewRepresentable"
  bluefly_code_required: NSViewRepresentable bridge
  consumer: BLU Studio
  justification: No native SwiftUI web rendering alternative exists.

3. Core Principles¶

Principle 1 — Apple Owns Apple¶

Before writing any implementation, verify whether the latest Apple SDK already owns the capability. If it does, adopt it. Do not recreate platform behavior.

Principle 2 — Upstream First¶

Decision order for every new capability: 1. Apple SDK 2. Mature upstream Swift package 3. Bluefly adapter (thin) 4. Bluefly implementation (last resort, requires documented justification)

Principle 3 — Net-Negative Ownership¶

Every Bluefly release targeting Apple platforms should reduce the volume of Bluefly-owned Swift code. Adoption and deletion are engineering deliverables alongside feature work.

Principle 4 — Incremental Modernization¶

Apple explicitly supports incremental migration for superseded APIs (ObservableObject → @Observable, XCTest → Swift Testing). Bluefly follows the same model: ratchet new code to the current API; migrate existing code in tracked increments.

Principle 5 — The Provider Compliance Report¶

The Apple Modernity Index (see APPLE-003) is a Provider Compliance Report, not a performance metric. It measures how closely BLU Studio consumes Apple's published contracts rather than working around them.

4. Upstream Drift Tracking¶

Each WWDC cycle updates the provider contract. Drift is tracked here rather than editing the principles.

Contract v1.0 → v1.1 (anticipated post-WWDC 2027)¶

Capability	v1.0 Status	v1.1 Delta	Action Required
Observation	Required for new code	—	Continue OBS-001 migration
Swift Testing	Required for new tests	—	Continue TEST-001 migration
SwiftUI	Current	TBD post-WWDC 2027	Review new Scene APIs
SwiftData	N/A (network app)	TBD	Reassess if offline capability added
AppIntents	Pending audit	TBD	Audit before v1.1
Liquid Glass / Design	Not yet audited	TBD	Audit before v1.1

Process: After each WWDC, issue a new contract version. Do not edit existing versions in place. The revision history below is the change log.

Contract Revision History¶

Version	Date	Baseline	Notes
1.0	2026-07	Swift 6, Xcode 27, macOS 15	Initial standard

5. Provider Contract — What Bluefly Must Never Reimplement¶

Capability	Apple Owner	Prohibited Bluefly Alternative
UI layout and rendering	SwiftUI	Custom layout engines, UIKit-style wrappers
State observation	Observation	Custom `@Published` chains, Redux-style stores
Navigation	NavigationSplitView / NavigationStack	Custom coordinator frameworks
Local persistence	SwiftData	Custom CoreData wrappers, hand-rolled SQLite
System actions / Siri	AppIntents	Custom intent parsing, proprietary shortcut systems
Widgets	WidgetKit	Custom notification extensions as widget substitutes
Device identity	DeviceCheck / App Attest	Custom device fingerprinting
Structured logging	OSLog	Custom logging frameworks, third-party log libraries
Test authorship	Swift Testing	Third-party test frameworks (Nimble, Quick, etc.)
Concurrency	Swift Concurrency	GCD wrappers, custom thread pools

Violation of this table requires a documented exception with evidence that Apple's API cannot meet the requirement.

6. Provider Invariant¶

Every provider capability is assumed authoritative until direct evidence demonstrates that local ownership is required. Retention of a local implementation requires evidence. Replacement of a provider capability requires evidence. Duplication requires evidence.

This invariant is universal. It applies identically to Apple, GitLab, Gas City, Drupal, Docker, Cloudflare, Keycloak, PostgreSQL, and every other provider in the platform.

Corollary — Temporary Ownership: A consumer may temporarily implement a capability the provider does not yet offer. The moment the provider's capability satisfies the required operational characteristics, the local implementation is reclassified as technical debt and SHALL be evaluated for removal.

Corollary — Evidence Required for Retention: A pre-existing local implementation may be retained only if evidence is produced that the provider's current capability does not satisfy the operational requirement. Absence of evidence is not justification for retention.

Corollary — Evaluation Is Mandatory; Removal Is Not: Debt classification guarantees tracking. It does not guarantee immediate removal. Removal is governed by the consumer's modernization timeline (APPLE-002 or equivalent).

Application to Apple capabilities:

Consumer Implementation	Provider Capability	Retention Justified?
Custom `ObservableObject` classes	`@Observable` (Swift 5.9+)	No — evaluate for removal (OBS-001)
XCTest suites	Swift Testing (Swift 5.10+)	No — evaluate for removal (TEST-001)
`@unchecked Sendable`	`actor` (Swift 5.7+)	No — evaluate for removal (CONC-001)
`WKWebView` bridge	No SwiftUI equivalent	Yes — provider does not yet own web rendering
OSLog `AppLogger` wrapper	`Logger` (OSLog)	Thin adapter only — acceptable