Docs/talk prep archive

.claude/docs/data-sources-api-research.md

@@ -386,15 +386,15 @@ let createdAt: FieldValue = .date(Date())
 
 // Reference to another record
 let categoryRef: FieldValue = .reference(
-    FieldValue.Reference(
+    Reference(
         recordName: "category-123",
         action: nil  // or "DELETE_SELF" for cascade delete
     )
 )
 
 // Location
 let location: FieldValue = .location(
-    FieldValue.Location(
+    Location(
         latitude: 37.7749,
         longitude: -122.4194
     )

.claude/docs/protocol-extraction-continuation.md

@@ -441,8 +441,8 @@ struct XcodeVersionRecord: CloudKitRecord {
     var version: String
     var buildNumber: String
     var releaseDate: Date
-    var swiftVersion: FieldValue.Reference  // Reference to SwiftVersionRecord
-    var macOSVersion: FieldValue.Reference  // Reference to another record
+    var swiftVersion: Reference  // Reference to SwiftVersionRecord
+    var macOSVersion: Reference  // Reference to another record
 
     // Implement protocol requirements...
 }

.codefactor.yml

@@ -0,0 +1,2 @@
+exclude:
+  - "Scripts/mermaid-to-pptx.py"

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
-  "name": "Swift 6.2",
-  "image": "swift:6.2",
+  "name": "Swift 6.3",
+  "image": "swift:6.3",
   "features": {
     "ghcr.io/devcontainers/features/common-utils:2": {
       "installZsh": "false",

.devcontainer/swift-6.1/devcontainer-lock.json

@@ -0,0 +1,14 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "version": "2.5.7",
+      "resolved": "ghcr.io/devcontainers/features/common-utils@sha256:dbf431d6b42d55cde50fa1df75c7f7c3999a90cde6d73f7a7071174b3c3d0cc4",
+      "integrity": "sha256:dbf431d6b42d55cde50fa1df75c7f7c3999a90cde6d73f7a7071174b3c3d0cc4"
+    },
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "1.3.5",
+      "resolved": "ghcr.io/devcontainers/features/git@sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251",
+      "integrity": "sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251"
+    }
+  }
+}

.devcontainer/swift-6.3/devcontainer.json

@@ -0,0 +1,32 @@
+{
+  "name": "Swift 6.3",
+  "image": "swift:6.3",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": "false",
+      "username": "vscode",
+      "upgradePackages": "false"
+    },
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "os-provided",
+      "ppa": "false"
+    }
+  },
+  "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
+  "runArgs": [
+    "--cap-add=SYS_PTRACE",
+    "--security-opt",
+    "seccomp=unconfined"
+  ],
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "lldb.library": "/usr/lib/liblldb.so"
+      },
+      "extensions": [
+        "sswg.swift-lang"
+      ]
+    }
+  },
+  "remoteUser": "root"
+} 

.github/actions/setup-tools/action.yml

@@ -0,0 +1,29 @@
+name: Setup mise tools
+description: >-
+  Restore (or build + save) the mise tool cache and put the binaries on PATH.
+  Implemented as a composite action so the cache scope is the caller job's
+  scope — reusable workflows scope caches separately, which silently breaks
+  hand-off between a setup job and a consumer lint job.
+
+runs:
+  using: composite
+  steps:
+    - name: Cache mise tools
+      id: mise-cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.local/share/mise/installs
+        key: mise-v2-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('mise.toml') }}
+        restore-keys: |
+          mise-v2-${{ runner.os }}-${{ runner.arch }}-
+    - name: Install mise tools (cache miss)
+      if: steps.mise-cache.outputs.cache-hit != 'true'
+      uses: jdx/mise-action@v4
+      with:
+        cache: false
+    - name: Configure PATH for cached mise tools
+      if: steps.mise-cache.outputs.cache-hit == 'true'
+      uses: jdx/mise-action@v4
+      with:
+        install: false
+        cache: false

.github/workflows/MistDemo-Integration.yml

@@ -0,0 +1,203 @@
+# MistDemo Integration Runs
+#
+# Live end-to-end runs against the real CloudKit container
+# (iCloud.com.brightdigit.MistDemo). Triggered on push to main and
+# release branches, and via manual workflow_dispatch (used to re-run
+# after rotating CLOUDKIT_WEB_AUTH_TOKEN).
+#
+# Required repo secrets:
+#   CLOUDKIT_API_TOKEN          - Web Services API token
+#   CLOUDKIT_WEB_AUTH_TOKEN     - Web-auth token (rotate when stale; manual)
+#   CLOUDKIT_KEY_ID             - Server-to-server key ID
+#   CLOUDKIT_PRIVATE_KEY_BASE64 - Server-to-server PEM, base64-encoded
+#                                 (base64 -w0 key.pem)
+#   CLOUDKIT_CONTAINER_ID       - iCloud.com.brightdigit.MistDemo
+#
+# Two-job design:
+#   1) `build` runs in `swift:6.3-noble`, installs the Swift Static
+#      Linux SDK (musl), and produces a self-contained statically
+#      linked mistdemo binary.
+#   2) `integration` runs on plain `ubuntu-24.04` (no Swift toolchain,
+#      no LD_LIBRARY_PATH needed) and executes the live CloudKit
+#      phases against the static binary.
+#
+# Secrets are NOT exposed to fork pull requests — there is no
+# pull_request trigger on this workflow by design.
+
+name: MistDemo Integration
+
+on:
+  push:
+    branches:
+      - main
+      - 'v*.*.*'
+  workflow_dispatch:
+
+concurrency:
+  group: mistdemo-integration-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build static mistdemo
+    runs-on: ubuntu-24.04
+    # Pin to an exact Swift patch — the Static Linux SDK URL + checksum
+    # below are tied to this same version. Bump together.
+    container: swift:6.3.2-noble
+    if: ${{ !contains(github.event.head_commit.message, 'ci skip') }}
+    timeout-minutes: 45
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Swift Static Linux SDK
+        run: |
+          set -euo pipefail
+          swift sdk install \
+            https://download.swift.org/swift-6.3.2-release/static-sdk/swift-6.3.2-RELEASE/swift-6.3.2-RELEASE_static-linux-0.1.0.artifactbundle.tar.gz \
+            --checksum 3fd798bef6f4408f1ea5a6f94ce4d4052830c4326ab85ebc04f983f01b3da407
+          swift sdk list
+
+      - name: swift build --swift-sdk x86_64-swift-linux-musl -c release
+        working-directory: Examples/MistDemo
+        run: swift build -c release --swift-sdk x86_64-swift-linux-musl
+
+      - name: Verify static linkage
+        working-directory: Examples/MistDemo
+        run: |
+          set -euo pipefail
+          BIN=.build/x86_64-swift-linux-musl/release/mistdemo
+          ls -lh "$BIN"
+          # A statically linked binary either reports "not a dynamic
+          # executable" (musl) or "statically linked" (glibc). Anything
+          # else means we picked up shared deps and broke the goal.
+          LDD_OUTPUT=$(ldd "$BIN" 2>&1 || true)
+          echo "$LDD_OUTPUT"
+          if ! echo "$LDD_OUTPUT" | grep -qE 'not a dynamic executable|statically linked'; then
+            echo "::error::Binary has dynamic dependencies; static link failed"
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: mistdemo
+          path: Examples/MistDemo/.build/x86_64-swift-linux-musl/release/mistdemo
+          retention-days: 1
+          # Single executable; default zip compression is fine.
+
+  integration:
+    name: Live CloudKit Integration
+    needs: build
+    runs-on: ubuntu-24.04
+    if: ${{ !contains(github.event.head_commit.message, 'ci skip') }}
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: mistdemo
+
+      - name: Prep binary
+        run: |
+          set -euo pipefail
+          chmod +x ./mistdemo
+          mkdir -p integration-logs
+          # Smoke check the binary before touching the network.
+          ./mistdemo --help >/dev/null
+
+      - name: Decode server-to-server private key
+        env:
+          CLOUDKIT_PRIVATE_KEY_BASE64: ${{ secrets.CLOUDKIT_PRIVATE_KEY_BASE64 }}
+        run: |
+          set -euo pipefail
+          KEY_PATH="$RUNNER_TEMP/cloudkit_s2s.pem"
+          printf '%s' "$CLOUDKIT_PRIVATE_KEY_BASE64" | base64 -d > "$KEY_PATH"
+          chmod 600 "$KEY_PATH"
+          # Defensive: mask the decoded PEM line-by-line so it can never
+          # land in step logs.
+          while IFS= read -r line; do
+            [ -n "$line" ] && echo "::add-mask::$line"
+          done < "$KEY_PATH"
+          echo "CLOUDKIT_PRIVATE_KEY_PATH=$KEY_PATH" >> "$GITHUB_ENV"
+
+      - name: test-public
+        timeout-minutes: 10
+        env:
+          CLOUDKIT_API_TOKEN: ${{ secrets.CLOUDKIT_API_TOKEN }}
+          CLOUDKIT_KEY_ID: ${{ secrets.CLOUDKIT_KEY_ID }}
+          CLOUDKIT_CONTAINER_ID: ${{ secrets.CLOUDKIT_CONTAINER_ID }}
+          CLOUDKIT_ENVIRONMENT: development
+        run: |
+          set -o pipefail
+          ./mistdemo test-public \
+            --record-count 5 \
+            --asset-size 50 \
+            2>&1 | tee integration-logs/test-public.log
+
+      - name: test-private
+        timeout-minutes: 10
+        env:
+          CLOUDKIT_API_TOKEN: ${{ secrets.CLOUDKIT_API_TOKEN }}
+          CLOUDKIT_WEB_AUTH_TOKEN: ${{ secrets.CLOUDKIT_WEB_AUTH_TOKEN }}
+          CLOUDKIT_CONTAINER_ID: ${{ secrets.CLOUDKIT_CONTAINER_ID }}
+          CLOUDKIT_ENVIRONMENT: development
+        run: |
+          set -o pipefail
+          ./mistdemo test-private \
+            --record-count 5 \
+            --asset-size 50 \
+            2>&1 | tee integration-logs/test-private.log
+
+      - name: demo-errors
+        timeout-minutes: 10
+        env:
+          CLOUDKIT_API_TOKEN: ${{ secrets.CLOUDKIT_API_TOKEN }}
+          CLOUDKIT_WEB_AUTH_TOKEN: ${{ secrets.CLOUDKIT_WEB_AUTH_TOKEN }}
+          CLOUDKIT_KEY_ID: ${{ secrets.CLOUDKIT_KEY_ID }}
+          CLOUDKIT_CONTAINER_ID: ${{ secrets.CLOUDKIT_CONTAINER_ID }}
+          CLOUDKIT_ENVIRONMENT: development
+        run: |
+          set -o pipefail
+          ./mistdemo demo-errors --scenario all \
+            2>&1 | tee integration-logs/demo-errors.log
+          # demo-errors exits 0 by design — assert all scenarios actually
+          # ran by checking for the per-scenario completion markers.
+          for marker in "401" "404" "409"; do
+            grep -q "$marker" integration-logs/demo-errors.log || {
+              echo "::error::demo-errors did not exercise scenario $marker"
+              exit 1
+            }
+          done
+
+      - name: demo-in-filter
+        timeout-minutes: 10
+        env:
+          CLOUDKIT_API_TOKEN: ${{ secrets.CLOUDKIT_API_TOKEN }}
+          CLOUDKIT_WEB_AUTH_TOKEN: ${{ secrets.CLOUDKIT_WEB_AUTH_TOKEN }}
+          CLOUDKIT_KEY_ID: ${{ secrets.CLOUDKIT_KEY_ID }}
+          CLOUDKIT_CONTAINER_ID: ${{ secrets.CLOUDKIT_CONTAINER_ID }}
+          CLOUDKIT_ENVIRONMENT: development
+        run: |
+          set -o pipefail
+          ./mistdemo demo-in-filter \
+            2>&1 | tee integration-logs/demo-in-filter.log
+
+      - name: Upload integration logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: integration-logs
+          path: integration-logs/
+          retention-days: 14
+          if-no-files-found: warn
+
+      - name: Cleanup decoded private key
+        if: always()
+        run: |
+          if [ -n "${CLOUDKIT_PRIVATE_KEY_PATH:-}" ] && [ -f "$CLOUDKIT_PRIVATE_KEY_PATH" ]; then
+            rm -f "$CLOUDKIT_PRIVATE_KEY_PATH"
+          fi