diff --git a/.agents/interfaces/.gitkeep b/.agents/interfaces/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/interfaces/macos/AssociatedObjects.swiftinterface b/.agents/interfaces/macos/AssociatedObjects.swiftinterface
new file mode 100644
index 0000000..a48208d
--- /dev/null
+++ b/.agents/interfaces/macos/AssociatedObjects.swiftinterface
@@ -0,0 +1,136 @@
+// swift-interface-format-version: 1.0
+// swift-compiler-version: Apple Swift version 6.4 (swiftlang-6.4.0.25.4 clang-2100.3.25.1)
+// swift-module-flags: -target arm64-apple-macosx12.0 -enable-objc-interop -language-mode 6 -Onone -module-name AssociatedObjects -package-name swift_associated_objects
+// swift-module-flags-ignorable:  -formal-cxx-interoperability-mode=off -interface-compiler-version 6.4
+import Foundation
+import Swift
+import _Concurrency
+import _StringProcessing
+import _SwiftConcurrencyShims
+public protocol AssociatingObject : AnyObject {
+  @discardableResult
+  @inlinable func setAssociatedObject<Object>(_ object: Object?, forKey key: Swift::StaticString, policy: ObjectiveC::objc_AssociationPolicy) -> Swift::Bool
+  @discardableResult
+  @inlinable func setAssociatedObject<Object>(_ object: Object?, forKey key: Swift::StaticString, threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety) -> Swift::Bool
+  @inlinable func getAssociatedObject<Object>(of type: Object.Type, forKey key: Swift::StaticString) -> Object?
+}
+extension AssociatedObjects::AssociatingObject {
+  @discardableResult
+  @inlinable public func setAssociatedObject<Object>(_ object: Object?, forKey key: Swift::StaticString, policy: ObjectiveC::objc_AssociationPolicy = .retain(.nonatomic)) -> Swift::Bool {
+		return _setAssociatedObject(
+			object,
+			to: self,
+			forKey: key,
+			policy: policy
+		)
+	}
+  @discardableResult
+  @inlinable public func setAssociatedObject<Object>(_ object: Object?, forKey key: Swift::StaticString, threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety) -> Swift::Bool {
+		return _setAssociatedObject(
+			object,
+			to: self,
+			forKey: key,
+			threadSafety: threadSafety
+		)
+	}
+  @inlinable public func getAssociatedObject<Object>(of type: Object.Type = Object.self, forKey key: Swift::StaticString) -> Object? {
+		return _getAssociatedObject(
+			forKey: key,
+			from: self
+		)
+	}
+}
+@discardableResult
+@inlinable public func _setAssociatedObject<Object>(_ object: Object?, to associatingObject: Swift::AnyObject, forKey key: Swift::StaticString, threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety = .nonatomic) -> Swift::Bool {
+	_setAssociatedObject(
+		object,
+		to: associatingObject,
+		forKey: key,
+		policy: .init(
+			Object.self is AnyClass ? .retain : .copy,
+			threadSafety
+		)
+	)
+}
+@discardableResult
+@inlinable public func _setAssociatedObject<Object>(_ object: Object?, to associatingObject: Swift::AnyObject, forKey key: Swift::StaticString, policy: ObjectiveC::objc_AssociationPolicy) -> Swift::Bool {
+	guard key.hasPointerRepresentation
+	else { return false }
+
+	objc_setAssociatedObject(
+		associatingObject,
+		UnsafeRawPointer(key.utf8Start),
+		object,
+		policy
+	)
+
+	return true
+}
+@inlinable public func _getAssociatedObject<Object>(of type: Object.Type = Object.self, forKey key: Swift::StaticString, from associatingObject: Swift::AnyObject) -> Object? {
+	guard key.hasPointerRepresentation
+	else { return nil }
+
+	return objc_getAssociatedObject(
+		associatingObject,
+		UnsafeRawPointer(key.utf8Start)
+	)
+	.flatMap { $0 as? Object }
+}
+extension ObjectiveC::NSObject : AssociatedObjects::AssociatingObject {
+}
+public enum _AssociationPolicyKind : Swift::String {
+  case copy
+  case assign
+  case retain
+  @inlinable public init?(rawValue: Swift::String)
+  public typealias RawValue = Swift::String
+  public var rawValue: Swift::String {
+    @inlinable get
+  }
+}
+public enum _AssociationPolicyThreadSafety : Swift::String {
+  case atomic
+  case nonatomic
+  @inlinable public init?(rawValue: Swift::String)
+  public typealias RawValue = Swift::String
+  public var rawValue: Swift::String {
+    @inlinable get
+  }
+}
+extension ObjectiveC::objc_AssociationPolicy {
+  @inlinable public init(_ kind: AssociatedObjects::_AssociationPolicyKind, _ threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety) {
+		switch kind {
+		case .copy:
+			self = .copy(threadSafety)
+		case .assign:
+			self = .assign
+		case .retain:
+			self = .retain(threadSafety)
+		}
+	}
+  @inlinable public static var assign: ObjectiveC::objc_AssociationPolicy {
+    get { .OBJC_ASSOCIATION_ASSIGN }
+  }
+  @inlinable public static func retain(_ threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety) -> ObjectiveC::objc_AssociationPolicy {
+		switch threadSafety {
+		case .atomic:
+				.OBJC_ASSOCIATION_RETAIN
+		case .nonatomic:
+				.OBJC_ASSOCIATION_RETAIN_NONATOMIC
+		}
+	}
+  @inlinable public static func copy(_ threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety) -> ObjectiveC::objc_AssociationPolicy {
+		switch threadSafety {
+		case .atomic:
+				.OBJC_ASSOCIATION_COPY
+		case .nonatomic:
+				.OBJC_ASSOCIATION_COPY_NONATOMIC
+		}
+	}
+}
+extension AssociatedObjects::_AssociationPolicyKind : Swift::Equatable {}
+extension AssociatedObjects::_AssociationPolicyKind : Swift::Hashable {}
+extension AssociatedObjects::_AssociationPolicyKind : Swift::RawRepresentable {}
+extension AssociatedObjects::_AssociationPolicyThreadSafety : Swift::Equatable {}
+extension AssociatedObjects::_AssociationPolicyThreadSafety : Swift::Hashable {}
+extension AssociatedObjects::_AssociationPolicyThreadSafety : Swift::RawRepresentable {}
diff --git a/.agents/interfaces/macos/AssociatedObjectsMacros.swiftinterface b/.agents/interfaces/macos/AssociatedObjectsMacros.swiftinterface
new file mode 100644
index 0000000..ddecc60
--- /dev/null
+++ b/.agents/interfaces/macos/AssociatedObjectsMacros.swiftinterface
@@ -0,0 +1,18 @@
+// swift-interface-format-version: 1.0
+// swift-compiler-version: Apple Swift version 6.4 (swiftlang-6.4.0.25.4 clang-2100.3.25.1)
+// swift-module-flags: -target arm64-apple-macosx12.0 -enable-objc-interop -language-mode 6 -Onone -module-name AssociatedObjectsMacros -package-name swift_associated_objects
+// swift-module-flags-ignorable:  -formal-cxx-interoperability-mode=off -interface-compiler-version 6.4
+@_exported import AssociatedObjects
+import Foundation
+import Swift
+import _Concurrency
+import _StringProcessing
+import _SwiftConcurrencyShims
+@attached(accessor) public macro AssociatedObject(policy: ObjectiveC::objc_AssociationPolicy, readonly: Swift::Bool) = #externalMacro(
+	module: "AssociatedObjectsMacrosPlugin",
+	type: "AssociatedObjectMacro"
+)
+@attached(accessor) public macro AssociatedObject(threadSafety: AssociatedObjects::_AssociationPolicyThreadSafety = .nonatomic, readonly: Swift::Bool = true) = #externalMacro(
+	module: "AssociatedObjectsMacrosPlugin",
+	type: "AssociatedObjectMacro"
+)
diff --git a/.agents/interfaces/macos/AssociatedObjectsMacrosPlugin.swiftinterface b/.agents/interfaces/macos/AssociatedObjectsMacrosPlugin.swiftinterface
new file mode 100644
index 0000000..de8e2a6
--- /dev/null
+++ b/.agents/interfaces/macos/AssociatedObjectsMacrosPlugin.swiftinterface
@@ -0,0 +1,25 @@
+// swift-interface-format-version: 1.0
+// swift-compiler-version: Apple Swift version 6.4 (swiftlang-6.4.0.25.4 clang-2100.3.25.1)
+// swift-module-flags: -target arm64-apple-macosx12.0 -enable-objc-interop -language-mode 6 -Onone -module-name AssociatedObjectsMacrosPlugin -package-name swift_associated_objects
+// swift-module-flags-ignorable:  -formal-cxx-interoperability-mode=off -interface-compiler-version 6.4
+import Foundation
+import MacroToolkit
+import Swift
+import SwiftCompilerPlugin
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+import _Concurrency
+import _StringProcessing
+import _SwiftConcurrencyShims
+public struct AssociatedObjectMacro : SwiftSyntaxMacros::AccessorMacro {
+  public static func expansion(of node: SwiftSyntax::AttributeSyntax, providingAccessorsOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [SwiftSyntax::AccessorDeclSyntax]
+}
+extension SwiftSyntaxMacros::MacroExpansionContext {
+  public func diagnose<T>(_ diagnostic: SwiftDiagnostics::Diagnostic, return value: T) -> T
+}
+public func == <A, B>(lhs: Swift::KeyPath<A, B>, rhs: B) -> (A) -> Swift::Bool where B : Swift::Equatable
+public func != <A, B>(lhs: Swift::KeyPath<A, B>, rhs: B) -> (A) -> Swift::Bool where B : Swift::Equatable
+public func || <A>(lhs: @escaping (A) -> Swift::Bool, rhs: @escaping (A) -> Swift::Bool) -> (A) -> Swift::Bool
+public func && <A>(lhs: @escaping (A) -> Swift::Bool, rhs: @escaping (A) -> Swift::Bool) -> (A) -> Swift::Bool
+prefix public func ! <A>(f: @escaping (A) -> Swift::Bool) -> (A) -> Swift::Bool
diff --git a/.github/workflows/generate-swiftinterface.yml b/.github/workflows/generate-swiftinterface.yml
new file mode 100644
index 0000000..a7a4239
--- /dev/null
+++ b/.github/workflows/generate-swiftinterface.yml
@@ -0,0 +1,120 @@
+name: Generate Swift interface
+run-name: Generate ${{ inputs.platform }} interfaces
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: Normalized platform name (macos, ios, linux, windows, wasi, ...)
+        required: true
+        type: string
+      target_branch:
+        description: Branch that receives the generated-interface PR (defaults to the dispatched branch)
+        required: false
+        default: ""
+        type: string
+  workflow_call:
+    inputs:
+      platform:
+        required: true
+        type: string
+      target_branch:
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  generate:
+    name: Generate ${{ inputs.platform }}
+    runs-on: ${{ (inputs.platform == 'linux' || inputs.platform == 'wasi') && 'ubuntu-latest' || inputs.platform == 'windows' && 'windows-latest' || 'macos-latest' }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+      INPUT_TARGET_BRANCH: ${{ inputs.target_branch }}
+      PLATFORM: ${{ inputs.platform }}
+    steps:
+      - name: Validate request
+        shell: bash
+        run: |
+          if [[ ! "$PLATFORM" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then
+            echo "Platform must be a normalized lowercase directory name: $PLATFORM" >&2
+            exit 1
+          fi
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.target_branch != '' && inputs.target_branch || github.ref_name }}
+
+      - name: Set up Swift outside Xcode
+        if: runner.os != 'macOS'
+        uses: SwiftyLab/setup-swift@v1
+        with:
+          swift-version: "6"
+          sdks: ${{ inputs.platform == 'wasi' && 'wasm' || '' }}
+
+      - name: Prepare generation branch
+        shell: bash
+        run: |
+          target_branch="${INPUT_TARGET_BRANCH:-$GITHUB_REF_NAME}"
+          interface_branch="automation/swiftinterfaces/$GITHUB_RUN_ID/$PLATFORM"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -C "$interface_branch"
+          echo "TARGET_BRANCH=$target_branch" >> "$GITHUB_ENV"
+          echo "INTERFACE_BRANCH=$interface_branch" >> "$GITHUB_ENV"
+
+      - name: Select WASI SDK
+        if: inputs.platform == 'wasi'
+        shell: bash
+        run: |
+          swift_sdk="$(swift sdk list | sed -nE '/(_wasm|wasi)/ { s/^[[:space:]]*([^[:space:]]+).*/\1/p; q; }')"
+          if [[ -z "$swift_sdk" ]]; then
+            echo "No installed WASI Swift SDK was found" >&2
+            swift sdk list >&2 || true
+            exit 1
+          fi
+          echo "SWIFT_SDK=$swift_sdk" >> "$GITHUB_ENV"
+
+      - name: Generate interface
+        shell: bash
+        run: |
+          interface_dir=".agents/interfaces/$PLATFORM"
+          if [[ -d "$interface_dir" ]]; then
+            find "$interface_dir" -maxdepth 1 -type f -name '*.swiftinterface' -delete
+          fi
+          if [[ -n "${SWIFT_SDK:-}" ]]; then
+            make swiftinterface platform="$PLATFORM" swift_sdk="$SWIFT_SDK"
+          else
+            make swiftinterface platform="$PLATFORM"
+          fi
+
+      - name: Commit and push interface
+        id: commit
+        shell: bash
+        run: |
+          git add --all -- ".agents/interfaces/$PLATFORM"
+          if git diff --cached --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No $PLATFORM interface changes" >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          git commit -m "Update $PLATFORM Swift interfaces"
+          git push --force-with-lease --set-upstream origin "$INTERFACE_BRANCH"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Open platform PR
+        if: steps.commit.outputs.changed == 'true'
+        shell: bash
+        run: |
+          pr_url="$(gh pr list --state open --base "$TARGET_BRANCH" --head "$INTERFACE_BRANCH" --json url --jq '.[0].url')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --base "$TARGET_BRANCH" \
+              --head "$INTERFACE_BRANCH" \
+              --title "chore: update $PLATFORM Swift interfaces" \
+              --body "Generated from \`$TARGET_BRANCH\` by workflow run $GITHUB_RUN_ID. Merge this PR into the aggregation branch after reviewing the platform-specific API snapshot.")"
+          fi
+          echo "$pr_url" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/update-swiftinterfaces.yml b/.github/workflows/update-swiftinterfaces.yml
new file mode 100644
index 0000000..27fc7c9
--- /dev/null
+++ b/.github/workflows/update-swiftinterfaces.yml
@@ -0,0 +1,85 @@
+name: Update Swift interfaces
+run-name: Update Swift interfaces from ${{ github.ref_name }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      platforms:
+        description: JSON array of independently generated platforms
+        required: true
+        default: '["macos","ios","tvos","watchos","maccatalyst"]'
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    name: Create aggregation branch
+    runs-on: ubuntu-latest
+    outputs:
+      update_branch: ${{ steps.branch.outputs.update_branch }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.ref_name }}
+
+      - name: Push aggregation branch
+        id: branch
+        shell: bash
+        run: |
+          update_branch="automation/swiftinterfaces/$GITHUB_RUN_ID"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -C "$update_branch"
+          git commit --allow-empty -m "Prepare Swift interface update"
+          git push --force-with-lease --set-upstream origin "$update_branch"
+          echo "update_branch=$update_branch" >> "$GITHUB_OUTPUT"
+
+  generate:
+    name: Generate ${{ matrix.platform }}
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: ${{ fromJSON(inputs.platforms) }}
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: ./.github/workflows/generate-swiftinterface.yml
+    with:
+      platform: ${{ matrix.platform }}
+      target_branch: ${{ needs.prepare.outputs.update_branch }}
+
+  finalize:
+    name: Open draft aggregation PR
+    if: always() && needs.prepare.result == 'success'
+    needs:
+      - prepare
+      - generate
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      TARGET_BRANCH: ${{ github.ref_name }}
+      UPDATE_BRANCH: ${{ needs.prepare.outputs.update_branch }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.ref_name }}
+
+      - name: Open draft PR
+        shell: bash
+        run: |
+          pr_url="$(gh pr list --state open --base "$TARGET_BRANCH" --head "$UPDATE_BRANCH" --json url --jq '.[0].url')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --draft \
+              --base "$TARGET_BRANCH" \
+              --head "$UPDATE_BRANCH" \
+              --title "chore: update platform Swift interfaces" \
+              --body "Aggregation PR for workflow run $GITHUB_RUN_ID. Merge the successful platform PRs into \`$UPDATE_BRANCH\`; failed platform jobs remain visible in the workflow and can be fixed or intentionally ignored. Matrix result: \`${{ needs.generate.result }}\`.")"
+          fi
+          echo "$pr_url" >> "$GITHUB_STEP_SUMMARY"
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..2abc2d4
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,7 @@
+output ?= .agents/interfaces
+platform ?= host
+swift_sdk ?=
+
+.PHONY: swiftinterface
+swiftinterface:
+	@./scripts/generate-swiftinterfaces.sh --package-path . --output "$(output)" --configuration debug --build-arg --build-system --build-arg native --platform "$(platform)" $(if $(swift_sdk),--swift-sdk "$(swift_sdk)")
diff --git a/scripts/generate-swiftinterfaces.sh b/scripts/generate-swiftinterfaces.sh
new file mode 100755
index 0000000..b028e55
--- /dev/null
+++ b/scripts/generate-swiftinterfaces.sh
@@ -0,0 +1,364 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+package_path="."
+output_path=".agents/interfaces"
+configuration="release"
+include_tests=false
+list_declared_platforms=false
+platform=""
+triple=""
+sdk=""
+swift_sdk=""
+scratch_path=""
+declare -a selected_targets=()
+declare -a build_arguments=()
+
+usage() {
+  sed -n '1,$p' <<'USAGE'
+Generate public Swift interfaces for one SwiftPM platform.
+
+Usage:
+  generate-swiftinterfaces.sh --platform <platform> [options]
+  generate-swiftinterfaces.sh --list-declared-platforms [options]
+
+Options:
+  --package-path <path>       Package root (default: .)
+  --output <path>             Platform-parent destination, relative to the package root
+                              unless absolute (default: .agents/interfaces)
+  --platform <name>           Output/build platform, for example macos, ios, linux,
+                              windows, or wasi; host resolves to the current platform
+  --list-declared-platforms   Print the Apple/custom platforms declared by Package.swift
+  --configuration <value>    debug or release (default: release)
+  --include-tests             Include Swift test targets
+  --target <name>             Generate one target; repeat to select several
+  --triple <triple>           Forward a target triple to SwiftPM
+  --sdk <path>                Forward an SDK path to SwiftPM
+  --swift-sdk <name>          Forward an installed Swift SDK name to SwiftPM
+  --scratch-path <path>       Use a specific SwiftPM scratch directory
+  --build-arg <argument>      Forward one additional argument to `swift build`; repeatable
+  -h, --help                  Show this help
+
+The platform name becomes an output directory. For example, --platform ios writes
+<output>/ios/<Module>.swiftinterface. Generate platforms in separate invocations so
+one unsupported platform does not suppress successful platform snapshots.
+USAGE
+}
+
+fail() {
+  printf 'swiftinterfaces: %s\n' "$*" >&2
+  exit 1
+}
+
+require_value() {
+  [[ $# -ge 2 ]] || fail "$1 requires a value"
+}
+
+host_platform() {
+  case "$(uname -s)" in
+    Darwin) printf 'macos\n' ;;
+    Linux) printf 'linux\n' ;;
+    MINGW*|MSYS*|CYGWIN*|Windows_NT) printf 'windows\n' ;;
+    *) fail "cannot infer a platform from host $(uname -s); pass --platform explicitly" ;;
+  esac
+}
+
+normalize_platform() {
+  local value
+  value="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
+  case "$value" in
+    osx|macosx) value="macos" ;;
+    iphoneos|iphonesimulator) value="ios" ;;
+    appletvos|appletvsimulator) value="tvos" ;;
+    watchsimulator) value="watchos" ;;
+    xros|xrsimulator) value="visionos" ;;
+    catalyst|mac-catalyst|mac_catalyst) value="maccatalyst" ;;
+    wasm|webassembly) value="wasi" ;;
+    host) value="$(host_platform)" ;;
+  esac
+  [[ "$value" =~ ^[a-z0-9][a-z0-9._-]*$ ]] || fail "invalid platform name: $1"
+  printf '%s\n' "$value"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --package-path)
+      require_value "$@"
+      package_path="$2"
+      shift 2
+      ;;
+    --output)
+      require_value "$@"
+      output_path="$2"
+      shift 2
+      ;;
+    --platform)
+      require_value "$@"
+      [[ -z "$platform" ]] || fail "--platform may be passed only once"
+      platform="$2"
+      shift 2
+      ;;
+    --list-declared-platforms)
+      list_declared_platforms=true
+      shift
+      ;;
+    --configuration)
+      require_value "$@"
+      configuration="$2"
+      shift 2
+      ;;
+    --include-tests)
+      include_tests=true
+      shift
+      ;;
+    --target)
+      require_value "$@"
+      selected_targets+=("$2")
+      shift 2
+      ;;
+    --triple)
+      require_value "$@"
+      triple="$2"
+      shift 2
+      ;;
+    --sdk)
+      require_value "$@"
+      sdk="$2"
+      shift 2
+      ;;
+    --swift-sdk)
+      require_value "$@"
+      swift_sdk="$2"
+      shift 2
+      ;;
+    --scratch-path)
+      require_value "$@"
+      scratch_path="$2"
+      shift 2
+      ;;
+    --build-arg)
+      require_value "$@"
+      build_arguments+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "unknown option: $1"
+      ;;
+  esac
+done
+
+case "$configuration" in
+  debug|release) ;;
+  *) fail "--configuration must be debug or release" ;;
+esac
+
+[[ "$list_declared_platforms" == false || -z "$platform" ]] || \
+  fail "--platform and --list-declared-platforms are separate operations"
+[[ "$list_declared_platforms" == true || -n "$platform" ]] || \
+  fail "--platform is required; use --list-declared-platforms to inspect Package.swift"
+
+command -v swift >/dev/null 2>&1 || fail "Swift is required"
+[[ -f "$script_dir/list-swift-targets.swift" ]] || fail "missing package parser beside generator"
+[[ -d "$package_path" ]] || fail "package path does not exist: $package_path"
+
+package_root="$(cd "$package_path" && pwd -P)"
+[[ -f "$package_root/Package.swift" ]] || fail "no Package.swift at $package_root"
+package_identity="$(basename "$package_root" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9_]/_/g')"
+
+if [[ -n "$platform" ]]; then
+  platform="$(normalize_platform "$platform")"
+fi
+
+if [[ -z "$scratch_path" ]]; then
+  scratch_root="$package_root/.build/swiftinterfaces/${platform:-metadata}/$configuration"
+elif [[ "$scratch_path" = /* ]]; then
+  scratch_root="$scratch_path"
+else
+  scratch_root="$package_root/$scratch_path"
+fi
+
+mkdir -p "$scratch_root/module-cache"
+
+description_file="$(mktemp "${TMPDIR:-/tmp}/swiftinterfaces-description.XXXXXX")"
+targets_file="$(mktemp "${TMPDIR:-/tmp}/swiftinterfaces-targets.XXXXXX")"
+platforms_file="$(mktemp "${TMPDIR:-/tmp}/swiftinterfaces-platforms.XXXXXX")"
+build_log="$(mktemp "${TMPDIR:-/tmp}/swiftinterfaces-build.XXXXXX")"
+cleanup() {
+  rm -f "$description_file" "$targets_file" "$platforms_file" "$build_log"
+}
+trap cleanup EXIT INT TERM
+
+(
+  cd "$package_root"
+  swift package describe --type json >"$description_file"
+)
+
+CLANG_MODULE_CACHE_PATH="$scratch_root/module-cache" \
+SWIFT_MODULECACHE_PATH="$scratch_root/module-cache" \
+  swift "$script_dir/list-swift-targets.swift" \
+    --list-platforms "$description_file" >"$platforms_file"
+
+if [[ "$list_declared_platforms" == true ]]; then
+  if [[ -s "$platforms_file" ]]; then
+    cat "$platforms_file"
+  else
+    printf 'swiftinterfaces: Package.swift declares no platforms; support must be proven by a platform build\n' >&2
+  fi
+  exit 0
+fi
+
+host="$(host_platform)"
+if [[ -z "$swift_sdk" ]]; then
+  sdk_name=""
+  default_triple=""
+  case "$platform" in
+    macos)
+      [[ "$host" == "macos" || -n "$triple" || -n "$sdk" ]] || \
+        fail "macos generation requires a macOS host or explicit cross-compilation options"
+      ;;
+    ios)
+      sdk_name="iphonesimulator"
+      default_triple="arm64-apple-ios-simulator"
+      ;;
+    tvos)
+      sdk_name="appletvsimulator"
+      default_triple="arm64-apple-tvos-simulator"
+      ;;
+    watchos)
+      sdk_name="watchsimulator"
+      default_triple="arm64-apple-watchos-simulator"
+      ;;
+    visionos)
+      sdk_name="xrsimulator"
+      default_triple="arm64-apple-xros-simulator"
+      ;;
+    maccatalyst)
+      sdk_name="macosx"
+      default_triple="arm64-apple-ios-macabi"
+      ;;
+    driverkit)
+      sdk_name="driverkit"
+      default_triple="arm64-apple-driverkit"
+      ;;
+    linux|windows)
+      [[ "$host" == "$platform" || -n "$triple" || -n "$sdk" ]] || \
+        fail "$platform generation requires a $platform host or explicit cross-compilation options"
+      ;;
+    wasi)
+      [[ -n "$triple" || -n "$sdk" ]] || \
+        fail "wasi generation requires --swift-sdk (recommended) or explicit --triple/--sdk options"
+      ;;
+    *)
+      [[ -n "$triple" || -n "$sdk" ]] || \
+        fail "custom platform $platform requires --swift-sdk or explicit --triple/--sdk options"
+      ;;
+  esac
+
+  if [[ -n "$sdk_name" ]]; then
+    [[ "$host" == "macos" ]] || fail "$platform generation requires Xcode on macOS"
+    command -v xcrun >/dev/null 2>&1 || fail "xcrun is required for $platform generation"
+    [[ -n "$sdk" ]] || sdk="$(xcrun --sdk "$sdk_name" --show-sdk-path)"
+    [[ -n "$triple" ]] || triple="$default_triple"
+  fi
+fi
+
+if [[ "$output_path" = /* ]]; then
+  output_parent="$output_path"
+else
+  output_parent="$package_root/$output_path"
+fi
+output_root="$output_parent/$platform"
+mkdir -p "$output_root"
+
+declare -a parser_arguments=("$description_file")
+if [[ "$include_tests" == true ]]; then
+  parser_arguments+=(--include-tests)
+fi
+if (( ${#selected_targets[@]} > 0 )); then
+  for target in "${selected_targets[@]}"; do
+    parser_arguments+=(--target "$target")
+  done
+fi
+
+CLANG_MODULE_CACHE_PATH="$scratch_root/module-cache" \
+SWIFT_MODULECACHE_PATH="$scratch_root/module-cache" \
+  swift "$script_dir/list-swift-targets.swift" "${parser_arguments[@]}" >"$targets_file"
+
+generated_count=0
+while IFS=$'\t' read -r target_name module_name target_type package_name; do
+  [[ -n "$target_name" && -n "$module_name" ]] || continue
+
+  printf 'Generating %s (%s) for %s...\n' "$module_name" "$target_name" "$platform"
+
+  declare -a common_command=(
+    swift build
+    --package-path "$package_root"
+    --scratch-path "$scratch_root"
+    --configuration "$configuration"
+    --enable-parseable-module-interfaces
+  )
+
+  [[ -z "$triple" ]] || common_command+=(--triple "$triple")
+  [[ -z "$sdk" ]] || common_command+=(--sdk "$sdk")
+  [[ -z "$swift_sdk" ]] || common_command+=(--swift-sdk "$swift_sdk")
+  if (( ${#build_arguments[@]} > 0 )); then
+    common_command+=("${build_arguments[@]}")
+  fi
+
+  declare -a command=("${common_command[@]}")
+  if [[ "$target_type" == "test" ]]; then
+    command+=(--build-tests -Xswiftc -enable-testing)
+  else
+    command+=(--target "$target_name")
+  fi
+
+  : >"$build_log"
+  if ! CLANG_MODULE_CACHE_PATH="$scratch_root/module-cache" \
+    SWIFT_MODULECACHE_PATH="$scratch_root/module-cache" \
+      "${command[@]}" 2>&1 | tee "$build_log"; then
+    if [[ "$target_type" != "test" ]] && \
+      grep -Eiq 'multiple targets.*(name|named)' "$build_log"; then
+      printf 'Target name is ambiguous; building root package products instead...\n'
+      : >"$build_log"
+      CLANG_MODULE_CACHE_PATH="$scratch_root/module-cache" \
+      SWIFT_MODULECACHE_PATH="$scratch_root/module-cache" \
+        "${common_command[@]}" 2>&1 | tee "$build_log"
+    else
+      fail "SwiftPM could not build target $target_name for $platform"
+    fi
+  fi
+
+  interface_path="$(
+    find "$scratch_root" -type f -name "$module_name.swiftinterface" \
+      -path "*/$package_name.build/*" -exec ls -t {} + 2>/dev/null | head -n 1 || true
+  )"
+  if [[ -z "$interface_path" ]]; then
+    interface_path="$(
+      find "$scratch_root" -type f -name "$module_name.swiftinterface" \
+        -exec grep -F -l -- "-package-name $package_identity" {} + 2>/dev/null | head -n 1 || true
+    )"
+  fi
+  if [[ -z "$interface_path" ]]; then
+    interface_path="$(
+      find "$scratch_root" -type f -name "$module_name.swiftinterface" \
+        -exec ls -t {} + 2>/dev/null | head -n 1 || true
+    )"
+  fi
+  [[ -n "$interface_path" && -f "$interface_path" ]] || \
+    fail "build succeeded but no public interface was found for $target_name ($module_name) on $platform"
+
+  temporary_output="$output_root/.$module_name.swiftinterface.$$"
+  cp "$interface_path" "$temporary_output"
+  chmod 0644 "$temporary_output"
+  mv "$temporary_output" "$output_root/$module_name.swiftinterface"
+  generated_count=$((generated_count + 1))
+done <"$targets_file"
+
+[[ $generated_count -gt 0 ]] || fail "no interfaces were generated for $platform"
+printf 'Generated %d interface(s) in %s\n' "$generated_count" "$output_root"
diff --git a/scripts/list-swift-targets.swift b/scripts/list-swift-targets.swift
new file mode 100755
index 0000000..b66371d
--- /dev/null
+++ b/scripts/list-swift-targets.swift
@@ -0,0 +1,100 @@
+#!/usr/bin/env swift
+
+import Foundation
+
+private struct PackageDescription: Decodable {
+    let name: String
+    let platforms: [Platform]
+    let targets: [Target]
+
+    struct Platform: Decodable {
+        let name: String
+        let version: String
+    }
+}
+
+private struct Target: Decodable {
+    let c99Name: String?
+    let moduleType: String?
+    let name: String
+    let type: String
+
+    enum CodingKeys: String, CodingKey {
+        case c99Name = "c99name"
+        case moduleType = "module_type"
+        case name
+        case type
+    }
+}
+
+private struct Options {
+    var includeTests = false
+    var listPlatforms = false
+    var selectedTargets = Set<String>()
+    var jsonPath: String?
+}
+
+private func fail(_ message: String) -> Never {
+    FileHandle.standardError.write(Data("swiftinterfaces: \(message)\n".utf8))
+    exit(1)
+}
+
+private var options = Options()
+private var arguments = Array(CommandLine.arguments.dropFirst())
+
+while !arguments.isEmpty {
+    let argument = arguments.removeFirst()
+    switch argument {
+    case "--include-tests":
+        options.includeTests = true
+    case "--list-platforms":
+        options.listPlatforms = true
+    case "--target":
+        guard !arguments.isEmpty else { fail("--target requires a value") }
+        options.selectedTargets.insert(arguments.removeFirst())
+    default:
+        guard !argument.hasPrefix("-") else { fail("unknown parser option: \(argument)") }
+        guard options.jsonPath == nil else { fail("expected exactly one package-description JSON file") }
+        options.jsonPath = argument
+    }
+}
+
+guard let jsonPath = options.jsonPath else { fail("missing package-description JSON file") }
+
+do {
+    let data = try Data(contentsOf: URL(fileURLWithPath: jsonPath))
+    let package = try JSONDecoder().decode(PackageDescription.self, from: data)
+    if options.listPlatforms {
+        guard options.selectedTargets.isEmpty, !options.includeTests else {
+            fail("--list-platforms cannot be combined with target-selection options")
+        }
+        for platform in package.platforms.sorted(by: { $0.name < $1.name }) {
+            print("\(platform.name)\t\(platform.version)")
+        }
+        exit(0)
+    }
+    let swiftTargets = package.targets.filter { target in
+        target.moduleType == "SwiftTarget" && (options.includeTests || target.type != "test")
+    }
+    let availableNames = Set(swiftTargets.map(\.name))
+    let unknownTargets = options.selectedTargets.subtracting(availableNames).sorted()
+
+    guard unknownTargets.isEmpty else {
+        fail("unknown or excluded Swift target(s): \(unknownTargets.joined(separator: ", "))")
+    }
+
+    let selected = swiftTargets
+        .filter { options.selectedTargets.isEmpty || options.selectedTargets.contains($0.name) }
+        .sorted { $0.name.localizedStandardCompare($1.name) == .orderedAscending }
+
+    guard !selected.isEmpty else { fail("the package has no matching Swift targets") }
+
+    for target in selected {
+        guard let moduleName = target.c99Name, !moduleName.isEmpty else {
+            fail("target \(target.name) does not have a Swift module name")
+        }
+        print("\(target.name)\t\(moduleName)\t\(target.type)\t\(package.name)")
+    }
+} catch {
+    fail("could not decode package description: \(error)")
+}