You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by ps...@apache.org on 2026/09/25 12:34:43 UTC

(opendal-yinyang) 04/06: feat: connect a native FSKit prototype to managed storage (#63)

This is an automated email from the ASF dual-hosted git repository.

PsiACE pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal-yinyang.git

commit 63ad20f50604c19edae88c8becc3a563dce36a22
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Fri Sep 25 20:34:27 2026 +0800

    feat: connect a native FSKit prototype to managed storage (#63)
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
---
 platforms/macos/FSKit/FSKit.entitlements  |   8 +
 platforms/macos/FSKit/FileSystem.swift    | 356 ++++++++++++++++++++++++++++++
 platforms/macos/FSKit/Info.plist          |  40 ++++
 platforms/macos/Host/App.swift            |  36 +++
 platforms/macos/Host/Host.entitlements    |   6 +
 platforms/macos/README.md                 |  60 +++++
 platforms/macos/Shared/NativeBridge.swift | 109 +++++++++
 platforms/macos/project.yml               |  63 ++++++
 specs/README.md                           |   1 +
 specs/macos-frontends.md                  |  49 ++++
 xtask/src/main.rs                         |  73 ++++++
 11 files changed, 801 insertions(+)

diff --git a/platforms/macos/FSKit/FSKit.entitlements b/platforms/macos/FSKit/FSKit.entitlements
new file mode 100644
index 0000000..8f89b37
--- /dev/null
+++ b/platforms/macos/FSKit/FSKit.entitlements
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>com.apple.security.app-sandbox</key><true/>
+<key>com.apple.security.network.client</key><true/>
+<key>com.apple.developer.fskit.fsmodule</key><true/>
+</dict></plist>
+
diff --git a/platforms/macos/FSKit/FileSystem.swift b/platforms/macos/FSKit/FileSystem.swift
new file mode 100644
index 0000000..56b7563
--- /dev/null
+++ b/platforms/macos/FSKit/FileSystem.swift
@@ -0,0 +1,356 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import Foundation
+import FSKit
+import OSLog
+
+@main
+struct YinYangExtension: UnaryFileSystemExtension {
+    var fileSystem: FSUnaryFileSystem & FSUnaryFileSystemOperations { YinYangFileSystem() }
+}
+final class YinYangFileSystem: FSUnaryFileSystem, FSUnaryFileSystemOperations {
+    private var resource: FSPathURLResource?
+    private let queue = DispatchQueue(label: "org.apache.yinyang.fskit.lifecycle")
+    func probeResource(resource: FSResource, replyHandler: @escaping (FSProbeResult?, Error?) -> Void) {
+        guard resource is FSPathURLResource else { return replyHandler(nil, POSIXError(.ENODEV)) }
+        replyHandler(.usable(name: "YinYang", containerID: FSContainerIdentifier(uuid: UUID())), nil)
+    }
+    func loadResource(resource: FSResource, options: FSTaskOptions, replyHandler: @escaping (FSVolume?, Error?) -> Void) {
+        queue.async {
+            guard self.resource == nil, let resource = resource as? FSPathURLResource,
+                  resource.url.startAccessingSecurityScopedResource() else {
+                return replyHandler(nil, POSIXError(.EACCES))
+            }
+            do {
+                let data = try Data(contentsOf: resource.url.appendingPathComponent("volume.json"))
+                guard var config = try JSONSerialization.jsonObject(with: data) as? [String: Any] else { throw POSIXError(.EINVAL) }
+                // Staging stays inside the explicitly selected isolated resource.
+                config["staging"] = resource.url.appendingPathComponent("mount-state").path
+                let bridge = try NativeBridge(config: config, mode: "mount")
+                let volume = try YinYangVolume(bridge: bridge)
+                self.resource = resource
+                self.containerStatus = .ready
+                replyHandler(volume, nil)
+            } catch {
+                resource.url.stopAccessingSecurityScopedResource()
+                replyHandler(nil, (error as? NativeFailure)?.posix ?? error)
+            }
+        }
+    }
+    func unloadResource(resource: FSResource, options: FSTaskOptions, replyHandler: @escaping (Error?) -> Void) {
+        queue.async {
+            self.resource?.url.stopAccessingSecurityScopedResource()
+            self.resource = nil
+            replyHandler(nil)
+        }
+    }
+}
+final class YinYangItem: FSItem {
+    let identity: String
+    let number: UInt64
+    var metadata: NativeItem
+    init(_ metadata: NativeItem, number: UInt64) {
+        identity = metadata.node
+        self.number = number
+        self.metadata = metadata
+        super.init()
+    }
+}
+final class YinYangVolume: FSVolume, FSVolume.Handler, FSVolume.ReadWriteHandler, FSVolume.DataCacheHandler {
+    let bridge: NativeBridge
+    let root: YinYangItem
+    private let queue = DispatchQueue(label: "org.apache.yinyang.fskit.requests")
+    private var items: [String: YinYangItem] = [:]
+    private var numbers: [String: UInt64] = [:]
+    private var nextID: UInt64 = 3
+    private var enumerations: [UInt64: (String, String)] = [:]
+    private var nextVerifier: UInt64 = 1
+    private var references: [String: Int] = [:]
+    private let logger = Logger(subsystem: "org.apache.yinyang.fskit", category: "io")
+    init(bridge: NativeBridge) throws {
+        self.bridge = bridge
+        let metadata = try bridge.item(["op": "root"])
+        root = YinYangItem(metadata, number: 2)
+        super.init(volumeID: FSVolume.Identifier(uuid: UUID(uuidString:
+            metadata.node.prefix(8) + "-" + metadata.node.dropFirst(8).prefix(4) + "-" +
+            metadata.node.dropFirst(12).prefix(4) + "-" + metadata.node.dropFirst(16).prefix(4) + "-" +
+            metadata.node.dropFirst(20)) ?? UUID()), volumeName: FSFileName(string: "YinYang"))
+        items[root.identity] = root
+        numbers[root.identity] = 2
+    }
+    private func item(_ raw: FSItem) throws -> YinYangItem {
+        guard let item = raw as? YinYangItem else { throw POSIXError(.EINVAL) }
+        return item
+    }
+    private func number(_ identity: String) -> UInt64 {
+        if let number = numbers[identity] { return number }
+        let number = nextID
+        nextID += 1
+        numbers[identity] = number
+        return number
+    }
+    private func remember(_ metadata: NativeItem) -> YinYangItem {
+        if let item = items[metadata.node] {
+            // A pinned directory enumeration may outlive a newer observation.
+            // Do not publish old attributes with a newer FSKit sequence number.
+            if metadata.generation >= item.metadata.generation { item.metadata = metadata }
+            return item
+        }
+        let item = YinYangItem(metadata, number: number(metadata.node))
+        items[metadata.node] = item
+        return item
+    }
+    private func attrs(_ item: YinYangItem) -> FSItem.Attributes {
+        let m = item.metadata
+        let result = FSItem.Attributes()
+        result.type = m.directory ? .directory : .file
+        result.fileID = FSItem.Identifier(rawValue: item.number)!
+        result.parentID = FSItem.Identifier(rawValue: number(m.parent ?? root.identity))!
+        result.size = m.size
+        result.allocSize = m.size
+        result.mode = m.directory || m.executable ? 0o755 : 0o644
+        result.uid = getuid()
+        result.gid = getgid()
+        result.linkCount = m.directory ? 2 : 1
+        result.flags = 0
+        result.modifyTime = timespec(tv_sec: Int(clamping: m.generation), tv_nsec: 0)
+        result.changeTime = result.modifyTime
+        result.accessTime = result.modifyTime
+        result.birthTime = timespec(tv_sec: 0, tv_nsec: 0)
+        return result
+    }
+    private func perform<T>(_ operation: @escaping () throws -> T, _ reply: @escaping (T?, Error?) -> Void) {
+        queue.async {
+            do { reply(try operation(), nil) }
+            catch {
+                self.logger.error("Operation failed: \(String(describing: error), privacy: .public)")
+                reply(nil, (error as? NativeFailure)?.posix ?? error)
+            }
+        }
+    }
+    private func checked<T>(_ result: T?) throws -> T {
+        guard let result else { throw POSIXError(.EIO) }
+        return result
+    }
+    var volumeStatistics: FSStatFSResult {
+        let result = FSStatFSResult(fileSystemTypeName: "yinyang")
+        result.blockSize = 4096
+        result.ioSize = 64 * 1024
+        return result
+    }
+    var supportedVolumeCapabilities: FSVolume.SupportedCapabilities {
+        let result = FSVolume.SupportedCapabilities()
+        result.caseFormat = .insensitiveCasePreserving
+        result.doesNotSupportVolumeSizes = true
+        result.doesNotSupportSettingFilePermissions = true
+        result.supportsSparseFiles = true
+        return result
+    }
+    var maximumLinkCount: Int { 1 }
+    var maximumNameLength: Int { 255 }
+    var restrictsOwnershipChanges: Bool { true }
+    var truncatesLongNames: Bool { false }
+    var maximumFileSizeInBits: Int { 63 }
+    var maximumXattrSizeInBits: Int { 0 }
+    func activateVolume(options: FSTaskOptions, replyHandler: @escaping (FSActivateResult?, Error?) -> Void) { replyHandler(FSActivateResult(rootItem: root), nil) }
+    func deactivateVolume(options: FSDeactivateOptions, replyHandler: @escaping (Error?) -> Void) { replyHandler(nil) }
+    func mount(options: FSTaskOptions, replyHandler: @escaping (Error?) -> Void) { replyHandler(nil) }
+    func unmount(replyHandler: @escaping () -> Void) { queue.async { replyHandler() } }
+    func synchronize(flags: FSSyncFlags, replyHandler: @escaping (Error?) -> Void) {
+        perform({ try self.bridge.call(["op": "fsync"]) }) { _, error in replyHandler(error) }
+    }
+    func getAttributes(_ desiredAttributes: FSItem.GetAttributesRequest, of raw: FSItem, context: FSContext, replyHandler: @escaping (FSGetAttributesResult?, Error?) -> Void) {
+        perform({
+            let item = try self.item(raw)
+            if !item.metadata.directory { try self.refresh(item) }
+            do { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+            catch let error as NativeFailure where error.kind == "NotFound" { /* Retained open-unlink metadata. */ }
+            return try self.checked(FSGetAttributesResult(attributes: self.attrs(item)))
+        }, replyHandler)
+    }
+    func setAttributes(_ requested: FSItem.SetAttributesRequest, on raw: FSItem, context: FSContext, replyHandler: @escaping (FSSetAttributesResult?, Error?) -> Void) {
+        perform({
+            let item = try self.item(raw)
+            // Validate the complete request before making any content change.
+            if requested.isValid(.mode) && requested.mode & 0o7777 != self.attrs(item).mode { throw POSIXError(.ENOTSUP) }
+            if requested.isValid(.flags) && requested.flags != 0 { throw POSIXError(.ENOTSUP) }
+            if requested.isValid(.uid) && requested.uid != getuid() { throw POSIXError(.ENOTSUP) }
+            if requested.isValid(.gid) && requested.gid != getgid() { throw POSIXError(.ENOTSUP) }
+            for attribute: FSItem.Attribute in [.accessTime, .modifyTime, .changeTime, .birthTime, .backupTime, .addedTime, .allocSize] {
+                if requested.isValid(attribute) { throw POSIXError(.ENOTSUP) }
+            }
+            if requested.isValid(.size) {
+                try self.bridge.call(["op": "truncate", "node": item.identity, "length": requested.size])
+                requested.consumedAttributes.insert(.size)
+            }
+            for attribute: FSItem.Attribute in [.mode, .flags, .uid, .gid] {
+                if requested.isValid(attribute) { requested.consumedAttributes.insert(attribute) }
+            }
+            item.metadata = try self.bridge.item(["op": "node", "node": item.identity])
+            return try self.checked(FSSetAttributesResult(attributes: self.attrs(item), freeSpace: nil))
+        }, replyHandler)
+    }
+    func lookupItem(named name: FSFileName, in directory: FSItem, context: FSContext, replyHandler: @escaping (FSLookupItemResult?, Error?) -> Void) {
+        perform({
+            guard let name = name.string else { throw POSIXError(.EINVAL) }
+            let directory = try self.item(directory)
+            if name == "." { return directory }
+            if name == ".." {
+                guard let parent = directory.metadata.parent else { return self.root }
+                return self.remember(try self.bridge.item(["op": "node", "node": parent]))
+            }
+            return self.remember(try self.bridge.item(["op": "lookup", "parent": directory.identity, "name": name]))
+        }) { (item: YinYangItem?, error) in
+            replyHandler(item.flatMap { FSLookupItemResult(foundItem: $0, itemName: FSFileName(string: $0.metadata.name), itemAttributes: self.attrs($0)) }, error)
+        }
+    }
+    func reclaimItem(_ raw: FSItem, replyHandler: @escaping (Error?) -> Void) {
+        perform({
+            let item = try self.item(raw)
+            var failure: Error?
+            _ = item.tryReclaim {
+                do { try self.bridge.call(["op": "release", "node": item.identity]) }
+                catch { failure = error }
+            }
+            if let failure { throw failure }
+            // Keep the numeric identity stable for the lifetime of the volume.
+            return true
+        }) { _, error in replyHandler(error) }
+    }
+    func readSymbolicLink(_ item: FSItem, context: FSContext, replyHandler: @escaping (FSReadSymlinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+    func createSymbolicLink(named name: FSFileName, in directory: FSItem, attributes: FSItem.SetAttributesRequest, linkContents: FSFileName, context: FSContext, replyHandler: @escaping (FSCreateSymlinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+    func createLink(to item: FSItem, named name: FSFileName, in directory: FSItem, context: FSContext, replyHandler: @escaping (FSCreateLinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+    func createItem(named name: FSFileName, type: FSItem.ItemType, in directory: FSItem, attributes: FSItem.SetAttributesRequest, context: FSContext, replyHandler: @escaping (FSCreateItemResult?, Error?) -> Void) {
+        perform({
+            guard type == .file || type == .directory, let name = name.string else { throw POSIXError(.ENOTSUP) }
+            if attributes.isValid(.mode) && type == .file && attributes.mode & 0o111 != 0 { throw POSIXError(.ENOTSUP) }
+            if attributes.isValid(.size) && attributes.size != 0 { throw POSIXError(.ENOTSUP) }
+            if attributes.isValid(.flags) && attributes.flags != 0 { throw POSIXError(.ENOTSUP) }
+            let parent = try self.item(directory)
+            let item = self.remember(try self.bridge.item(["op": "create", "parent": parent.identity, "name": name, "directory": type == .directory]))
+            parent.metadata = try self.bridge.item(["op": "node", "node": parent.identity])
+            return try self.checked(FSCreateItemResult(newItem: item, newItemName: FSFileName(string: item.metadata.name), newItemAttributes: self.attrs(item), directoryAttributes: self.attrs(parent), freeSpace: nil))
+        }, replyHandler)
+    }
+    func removeItem(_ raw: FSItem, named name: FSFileName, from directory: FSItem, context: FSContext, replyHandler: @escaping (FSRemoveItemResult?, Error?) -> Void) {
+        perform({
+            let item = try self.item(raw), parent = try self.item(directory)
+            try self.bridge.call(["op": "remove", "node": item.identity])
+            parent.metadata = try self.bridge.item(["op": "node", "node": parent.identity])
+            let removed = self.attrs(item)
+            removed.linkCount = 0
+            return try self.checked(FSRemoveItemResult(itemAttributes: removed, directoryAttributes: self.attrs(parent), freeSpace: nil))
+        }, replyHandler)
+    }
+    func renameItem(_ raw: FSItem, inDirectory sourceDirectory: FSItem, named sourceName: FSFileName, to destinationName: FSFileName, inDirectory destinationDirectory: FSItem, overItem: FSItem?, context: FSContext, replyHandler: @escaping (FSRenameItemResult?, Error?) -> Void) {
+        perform({
+            guard let name = destinationName.string else { throw POSIXError(.EINVAL) }
+            try self.bridge.call(["op": "rename", "node": self.item(raw).identity, "parent": self.item(destinationDirectory).identity, "name": name, "replace": overItem != nil])
+            let item = try self.item(raw), source = try self.item(sourceDirectory), destination = try self.item(destinationDirectory)
+            for item in [item, source, destination] { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+            let replaced = try overItem.map { self.attrs(try self.item($0)) }
+            replaced?.linkCount = 0
+            return try self.checked(FSRenameItemResult(newName: FSFileName(string: name), renamedItemAttributes: self.attrs(item), sourceDirectoryAttributes: self.attrs(source), destinationDirectoryAttributes: self.attrs(destination), overItemAttributes: replaced, freeSpace: nil))
+        }, replyHandler)
+    }
+    func enumerateDirectory(_ raw: FSItem, startingAt cookie: FSDirectoryCookie, verifier: FSDirectoryVerifier, attributes: FSItem.GetAttributesRequest?, packer: FSDirectoryEntryPacker, context: FSContext, replyHandler: @escaping (FSEnumerateDirectoryResult?, Error?) -> Void) {
+        perform({
+            let directory = try self.item(raw)
+            var request: [String: Any] = ["op": "scan", "node": directory.identity, "offset": cookie.rawValue, "limit": 256]
+            let currentVerifier: UInt64
+            if cookie.rawValue == 0 {
+                currentVerifier = self.nextVerifier
+                self.nextVerifier += 1
+                if self.enumerations.count >= 1024, let oldest = self.enumerations.keys.min() {
+                    self.enumerations.removeValue(forKey: oldest)
+                }
+            } else {
+                currentVerifier = verifier.rawValue
+                guard let (identity, revision) = self.enumerations[verifier.rawValue], identity == directory.identity else { throw POSIXError(.ESTALE) }
+                request["revision"] = revision
+            }
+            var offset = cookie.rawValue
+            while true {
+                request["offset"] = offset
+                let page = try self.bridge.call(request)
+                guard let revision = page["revision"] as? String, let entries = page["entries"] as? [[String: Any]] else { throw POSIXError(.EIO) }
+                self.enumerations[currentVerifier] = (directory.identity, revision)
+                request["revision"] = revision
+                for value in entries {
+                    let item = self.remember(try NativeItem(value))
+                    if !packer.packEntry(name: FSFileName(string: item.metadata.name), itemType: item.metadata.directory ? .directory : .file,
+                        itemID: FSItem.Identifier(rawValue: item.number)!, nextCookie: FSDirectoryCookie(offset + 1),
+                        attributes: self.attrs(item)) { return currentVerifier }
+                    offset += 1
+                }
+                if page["next"] is NSNull { break }
+            }
+            return currentVerifier
+        }) { value, error in replyHandler(value.flatMap { FSEnumerateDirectoryResult(verifier: $0) }, error) }
+    }
+    func read(from raw: FSItem, at offset: off_t, length: Int, into buffer: FSMutableFileDataBuffer, replyHandler: @escaping (FSReadFileResult?, Error?) -> Void) {
+        perform({
+            guard offset >= 0, length >= 0 else { throw POSIXError(.EINVAL) }
+            let item = try self.item(raw)
+            try self.refresh(item)
+            let data = try self.bridge.read(node: item.identity, offset: UInt64(offset), length: length)
+            _ = buffer.withUnsafeMutableBytes { target in data.copyBytes(to: target) }
+            do { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+            catch let error as NativeFailure where error.kind == "NotFound" { /* Retained unlinked read. */ }
+            guard let result = FSReadFileResult(bytesRead: data.count, itemAttributes: self.attrs(item)) else { throw POSIXError(.EIO) }
+            return result
+        }, replyHandler)
+    }
+    private func refresh(_ item: YinYangItem) throws {
+        do { try bridge.call(["op": "refresh", "node": item.identity]) }
+        catch let error as NativeFailure where error.kind == "Busy" || error.kind == "NotFound" { /* Retain dirty or unlinked bytes. */ }
+    }
+    func write(contents: Data, to raw: FSItem, at offset: off_t, replyHandler: @escaping (FSWriteFileResult?, Error?) -> Void) {
+        perform({
+            guard offset >= 0 else { throw POSIXError(.EINVAL) }
+            let item = try self.item(raw)
+            try self.bridge.write(node: item.identity, offset: UInt64(offset), data: contents)
+            item.metadata.size = max(item.metadata.size, UInt64(offset) + UInt64(contents.count))
+            guard let result = FSWriteFileResult(bytesWritten: contents.count, itemAttributes: self.attrs(item), freeSpace: nil) else { throw POSIXError(.EIO) }
+            return result
+        }, replyHandler)
+    }
+    func open(_ raw: FSItem, modes: FSVolume.OpenModes, cacheMode: FSVolume.DataCacheMode, context: FSContext, replyHandler: @escaping (FSOpenItemResult?, Error?) -> Void) {
+        perform({
+            let item = try self.item(raw)
+            self.references[item.identity, default: 0] += 1
+            return FSOpenItemResult(grantedCoherency: .noCache)
+        }, replyHandler)
+    }
+    func upgrade(_ item: FSItem, cacheMode: FSVolume.DataCacheMode, context: FSContext, replyHandler: @escaping (FSUpgradeItemResult?, Error?) -> Void) {
+        replyHandler(FSUpgradeItemResult(grantedCoherency: .noCache), nil)
+    }
+    func close(_ raw: FSItem, context: FSContext, replyHandler: @escaping () -> Void) {
+        queue.async {
+            do {
+                let item = try self.item(raw)
+                let remaining = max(0, self.references[item.identity, default: 1] - 1)
+                self.references[item.identity] = remaining
+                try self.bridge.call(["op": "fsync"])
+                if remaining == 0 { try self.bridge.call(["op": "release", "node": item.identity]) }
+            } catch { self.logger.error("Close retained pending state: \(String(describing: error), privacy: .public)") }
+            replyHandler()
+        }
+    }
+}
diff --git a/platforms/macos/FSKit/Info.plist b/platforms/macos/FSKit/Info.plist
new file mode 100644
index 0000000..7c0408e
--- /dev/null
+++ b/platforms/macos/FSKit/Info.plist
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>YinYang file system</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>EXAppExtensionAttributes</key>
+	<dict>
+		<key>EXExtensionPointIdentifier</key>
+		<string>com.apple.fskit.fsmodule</string>
+		<key>FSActivateOptionSyntax</key>
+		<dict>
+			<key>shortOptions</key>
+			<string></string>
+		</dict>
+		<key>FSRequiresSecurityScopedPathURLResources</key>
+		<true/>
+		<key>FSShortName</key>
+		<string>yinyang</string>
+		<key>FSSupportsBlockResources</key>
+		<false/>
+		<key>FSSupportsPathURLs</key>
+		<true/>
+	</dict>
+</dict>
+</plist>
diff --git a/platforms/macos/Host/App.swift b/platforms/macos/Host/App.swift
new file mode 100644
index 0000000..adba279
--- /dev/null
+++ b/platforms/macos/Host/App.swift
@@ -0,0 +1,36 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import SwiftUI
+import FSKit
+
+@main
+struct YinYangPrototype: App {
+    var body: some Scene {
+        WindowGroup {
+            VStack(alignment: .leading, spacing: 16) {
+                Text("YinYang native prototype").font(.title)
+                Text("Use an isolated directory containing volume.json. Enable the file system extension, then mount it with mount -F -t yinyang SOURCE TARGET.")
+                    .textSelection(.enabled)
+                Button("Open File System Extensions") { _ = FSClient.shared.openFileSystemExtensionsSettings() }
+                Text("Experimental: no production support or existing sync folders.").font(.caption)
+            }.padding(24).frame(width: 540)
+        }
+    }
+}
+
diff --git a/platforms/macos/Host/Host.entitlements b/platforms/macos/Host/Host.entitlements
new file mode 100644
index 0000000..95cd70e
--- /dev/null
+++ b/platforms/macos/Host/Host.entitlements
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>com.apple.security.app-sandbox</key><true/>
+</dict></plist>
+
diff --git a/platforms/macos/README.md b/platforms/macos/README.md
new file mode 100644
index 0000000..89971f6
--- /dev/null
+++ b/platforms/macos/README.md
@@ -0,0 +1,60 @@
+# macOS native prototypes
+
+Requires macOS 27, Xcode 27, XcodeGen and the repository Rust toolchain. These
+extensions operate on isolated test volumes only. See
+[the specification](../../specs/macos-frontends.md) for supported semantics.
+
+Build without signing:
+
+```sh
+cargo x macos
+```
+
+Build with a local Developer ID identity and a profile authorizing the FSKit
+module entitlement for `com.xuanwo.yinyang.prototype.fskit`:
+
+```sh
+cargo x macos --identity 'Developer ID Application: NAME (TEAM)' \
+  --team TEAM --fskit-profile 'FSKit profile name'
+```
+
+The result is `target/macos/DerivedData/Build/Products/Debug/YinYang.app`.
+Open the host, enable its filesystem extension in System Settings, and check
+`pluginkit -m -v -i com.xuanwo.yinyang.prototype.fskit` points to this build.
+An older extension with the same identifier must not be used for acceptance.
+
+Create an isolated resource directory with `volume.json` describing an **existing**
+Managed filesystem. Use dedicated test credentials and restrictive file
+permissions; never commit credentials or provisioning profiles.
+
+```json
+{
+  "profile": "minio",
+  "storage": {
+    "endpoint": "http://127.0.0.1:19000",
+    "bucket": "isolated-test-bucket",
+    "root": "isolated-prefix",
+    "region": "us-east-1",
+    "access_key_id": "TEST_KEY",
+    "secret_access_key": "TEST_SECRET"
+  }
+}
+```
+
+The adapter supplies staging beneath the selected resource. Mount into a separate
+empty directory using absolute paths:
+
+```sh
+mount -F -t yinyang /absolute/test-resource /absolute/test-mount
+```
+
+Acceptance must check `mount` reports `yinyang` before and after I/O, and compare
+results with an independent `yy restore` from the same remote filesystem. An
+extension crash can unmount the volume and expose the underlying local directory;
+successful local writes alone do not establish native or remote correctness.
+
+Exercise multiple descriptors, close-one/write-another, fsync, truncate, safe-save
+replacement, directory pagination, independent remote updates, backend outage and
+extension restart with the original staging directory. Do not remove pending
+staging or use an existing user sync directory. Unmount before rebuilding; ensure
+the next launch runs the newly built extension rather than the previous process.
diff --git a/platforms/macos/Shared/NativeBridge.swift b/platforms/macos/Shared/NativeBridge.swift
new file mode 100644
index 0000000..dd7fe9f
--- /dev/null
+++ b/platforms/macos/Shared/NativeBridge.swift
@@ -0,0 +1,109 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import Foundation
+
+struct NativeFailure: Error {
+    let kind: String
+    let message: String
+    var posix: Error {
+        let code: POSIXErrorCode
+        switch kind {
+        case "NotFound": code = .ENOENT
+        case "AlreadyExists": code = .EEXIST
+        case "NotDirectory": code = .ENOTDIR
+        case "IsDirectory": code = .EISDIR
+        case "NotEmpty": code = .ENOTEMPTY
+        case "ReadOnly": code = .EROFS
+        case "PermissionDenied": code = .EACCES
+        case "Busy", "Frozen": code = .EBUSY
+        case "Conflict", "Retryable": code = .EAGAIN
+        case "Invalid", "InvalidName": code = .EINVAL
+        case "Unsupported": code = .ENOTSUP
+        case "NoSpace": code = .ENOSPC
+        case "TooLarge": code = .EFBIG
+        default: code = .EIO
+        }
+        return POSIXError(code)
+    }
+}
+struct NativeItem: Decodable {
+    let node: String
+    let parent: String?
+    let name: String
+    let directory: Bool
+    var size: UInt64
+    let executable: Bool
+    let generation: UInt64
+    let revision: String
+    init(_ value: [String: Any]) throws {
+        self = try JSONDecoder().decode(Self.self, from: JSONSerialization.data(withJSONObject: value))
+    }
+}
+final class NativeBridge {
+    private let session: UInt64
+    static func invoke(_ value: [String: Any]) throws -> [String: Any] {
+        let input = try JSONSerialization.data(withJSONObject: value)
+        let output = input.withUnsafeBytes {
+            yy_native_call($0.baseAddress?.assumingMemoryBound(to: UInt8.self), $0.count)
+        }
+        guard let output else { throw POSIXError(.ENOMEM) }
+        defer { yy_native_free(output) }
+        let result = try JSONSerialization.jsonObject(with: Data(String(cString: output).utf8)) as? [String: Any]
+        if let error = result?["error"] as? [String: Any] {
+            throw NativeFailure(kind: error["kind"] as? String ?? "Io",
+                                message: error["message"] as? String ?? "Native operation failed")
+        }
+        guard let ok = result?["ok"] as? [String: Any] else { throw POSIXError(.EIO) }
+        return ok
+    }
+    init(config: [String: Any], mode: String) throws {
+        let result = try Self.invoke(["action": "connect", "config": config, "mode": mode])
+        guard let id = result["session"] as? NSNumber else { throw POSIXError(.EIO) }
+        session = id.uint64Value
+    }
+    deinit { _ = try? Self.invoke(["action": "close", "session": session]) }
+    @discardableResult
+    func call(_ request: [String: Any]) throws -> [String: Any] {
+        try Self.invoke(["action": "call", "session": session, "request": request])
+    }
+    func item(_ request: [String: Any]) throws -> NativeItem { try NativeItem(call(request)) }
+    func read(node: String, offset: UInt64, length: Int, revision: String? = nil) throws -> Data {
+        var output = Data()
+        while output.count < length {
+            let count = min(length - output.count, 1024 * 1024)
+            var request: [String: Any] = ["op": revision == nil ? "read" : "download",
+                "node": node, "offset": offset + UInt64(output.count), "length": count]
+            if let revision { request["revision"] = revision }
+            let response = try call(request)
+            guard let bytes = response["bytes"] as? [UInt8] else { throw POSIXError(.EIO) }
+            output.append(contentsOf: bytes)
+            if bytes.count < count { break }
+        }
+        return output
+    }
+    func write(node: String, offset: UInt64, data: Data) throws {
+        var position = 0
+        while position < data.count {
+            let end = min(position + 1024 * 1024, data.count)
+            try call(["op": "write", "node": node, "offset": offset + UInt64(position),
+                      "bytes": Array(data[position..<end])])
+            position = end
+        }
+    }
+}
diff --git a/platforms/macos/project.yml b/platforms/macos/project.yml
new file mode 100644
index 0000000..53ae715
--- /dev/null
+++ b/platforms/macos/project.yml
@@ -0,0 +1,63 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: YinYang
+options:
+  deploymentTarget:
+    macOS: "27.0"
+settings:
+  base:
+    SWIFT_VERSION: "5.0"
+    CODE_SIGN_STYLE: Manual
+    CODE_SIGN_IDENTITY: "-"
+    MACOSX_DEPLOYMENT_TARGET: "27.0"
+    ENABLE_HARDENED_RUNTIME: YES
+    GENERATE_INFOPLIST_FILE: YES
+    SWIFT_EMIT_LOC_STRINGS: NO
+    CURRENT_PROJECT_VERSION: "1"
+    MARKETING_VERSION: "1.0"
+targets:
+  YinYang:
+    type: application
+    platform: macOS
+    sources: [Host]
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.xuanwo.yinyang.prototype
+        CODE_SIGN_ENTITLEMENTS: "$(YINYANG_SOURCE_ROOT)/platforms/macos/Host/Host.entitlements"
+        INFOPLIST_KEY_CFBundleDisplayName: YinYang Prototype
+        PROVISIONING_PROFILE_SPECIFIER: ""
+    dependencies:
+      - target: YinYangFSKit
+        embed: true
+  YinYangFSKit:
+    type: extensionkit-extension
+    platform: macOS
+    sources: [Shared, FSKit]
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.xuanwo.yinyang.prototype.fskit
+        INFOPLIST_FILE: "$(YINYANG_SOURCE_ROOT)/platforms/macos/FSKit/Info.plist"
+        CODE_SIGN_ENTITLEMENTS: "$(YINYANG_SOURCE_ROOT)/platforms/macos/FSKit/FSKit.entitlements"
+        PROVISIONING_PROFILE_SPECIFIER: "$(YINYANG_FSKIT_PROFILE)"
+        SWIFT_OBJC_BRIDGING_HEADER: "$(YINYANG_BRIDGING_HEADER)"
+        OTHER_LDFLAGS: ["$(inherited)", "$(YINYANG_NATIVE_LIBRARY)", "-framework", Security, "-framework", SystemConfiguration, "-lc++"]
+schemes:
+  YinYang:
+    build:
+      targets:
+        YinYang: all
diff --git a/specs/README.md b/specs/README.md
index e60005d..7d2ff38 100644
--- a/specs/README.md
+++ b/specs/README.md
@@ -12,6 +12,7 @@ This directory contains the maintained contracts for Apache OpenDALâ„¢ YinYang.
 | [Mount runtime](mount-runtime.md) | Instance-local shared nodes, explicit refresh, remote fsync, and retained failures. |
 | [Sync runtime](sync-runtime.md) | Baseline-bound local edits, conditional publication, conflict retention, and exact retry. |
 | [Native bridge](native-bridge.md) | In-process ownership and private adapter request semantics. |
+| [Experimental macOS frontends](macos-frontends.md) | Native FSKit and File Provider integration boundaries. |
 | [Volume capabilities](volume-capabilities.md) | Configuration, four-layer admission, read-only enforcement, and CLI status. |
 | [Transactional filesystem](transactional-filesystem.md) | Shared target contract. Object-storage and metadata-service bindings implemented experimentally. |
 
diff --git a/specs/macos-frontends.md b/specs/macos-frontends.md
new file mode 100644
index 0000000..be66245
--- /dev/null
+++ b/specs/macos-frontends.md
@@ -0,0 +1,49 @@
+# Experimental macOS frontends
+
+**Status: prototypes on macOS 27 / Xcode 27, not production volume support.**
+
+The adapters link `yinyang-native` and use the same Authority, Mount and Sync
+coordinators as library callers. `cargo x macos` builds a host and an FSKit
+extension. Signing and OS registration are explicit operator actions, not build
+side effects. Neither adapter initializes or reformats remote storage.
+
+## FSKit Mount
+
+The FSKit path resource is an explicitly selected directory containing
+`volume.json`; durable staging is its `mount-state` child. The extension obtains
+the security-scoped resource before reading either.
+
+The volume uses core NodeIds internally and stable volume-lifetime numeric inode
+IDs at the kernel boundary. Directory verifiers retain an immutable revision;
+cookies are ordinal positions, not live-list offsets. At most 1024 enumerations
+are retained; an evicted verifier returns ESTALE. The item identity map currently
+lives until unmount and is not a large-tree memory scalability claim.
+
+All filesystem callbacks serialize off the main thread. DataCacheHandler grants
+`noCache`; clean reads refresh the shared Mount node, while dirty and unlinked
+nodes retain staged bytes. This favors correctness over read performance and
+does not claim mmap, kernel-cache invalidation or a distributed POSIX cache.
+The macOS 27 read/write result objects carry updated attributes back to FSKit.
+
+**Concurrent external length changes are not supported by this prototype.** On
+the tested macOS 27 build, the kernel can retain the old EOF despite newer
+attributes returned by read/get-attributes handlers. Data-cache invalidation alone
+does not establish metadata coherence. Remount before consuming externally
+resized files. This is an acceptance blocker for multi-client writable Mount;
+the uncached data path alone is not evidence that this contract is satisfied.
+
+Reads, writes, truncate, create, mkdir, unlink, rmdir, enumeration and atomic
+replace rename use the real runtime. Volume synchronization publishes staged
+content and propagates errors. The non-reporting close callback attempts fsync,
+logs a failure and retains staged state; close is not an error-reporting durability
+boundary. Recovery reopens the same staging directory and original frozen request.
+
+Ownership and modes are synthesized (current uid/gid, files 0644 or 0755 according
+to the core executable flag, directories 0755). Creation does not persist requested
+permissions. Timestamps encode generation, not wall-clock times. Permission and
+timestamp changes, links and extended attributes are unsupported. There is no
+disk capacity claim. Unsupported metadata is not marked consumed.
+
+There is no conflict-resolution UI. Retained failures and bytes remain in the
+runtime staging journal; operators must not delete that directory to recover a
+failed write.
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 94f97ea..5e41ceb 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -41,6 +41,7 @@ impl Command {
             SubCommand::Licenses(cmd) => cmd.run(),
             SubCommand::Lint(cmd) => cmd.run(),
             SubCommand::Test(cmd) => cmd.run(),
+            SubCommand::Macos(cmd) => cmd.run(),
         }
     }
 }
@@ -55,6 +56,78 @@ enum SubCommand {
     Lint(CommandLint),
     #[clap(about = "Run all workspace tests.")]
     Test(CommandTest),
+    #[clap(about = "Build the macOS native prototypes (requires Xcode 27 and XcodeGen).")]
+    Macos(CommandMacos),
+}
+
+#[derive(Parser)]
+struct CommandMacos {
+    #[arg(long, default_value = "target/macos")]
+    output: std::path::PathBuf,
+    #[arg(long, requires_all = ["team", "fskit_profile"])]
+    identity: Option<String>,
+    #[arg(long, requires = "identity")]
+    team: Option<String>,
+    #[arg(long, requires = "identity")]
+    fskit_profile: Option<String>,
+}
+impl CommandMacos {
+    fn run(self) {
+        if !cfg!(target_os = "macos") {
+            panic!("native macOS build requires macOS");
+        }
+        let root = std::path::Path::new(env!("CARGO_WORKSPACE_DIR"));
+        let output = root.join(self.output);
+        let target =
+            root.join(std::env::var_os("CARGO_TARGET_DIR").unwrap_or_else(|| "target".into()));
+        let mut cargo = find_command("cargo");
+        cargo.args(["build", "-p", "yinyang-native"]);
+        run_command(cargo);
+        std::fs::create_dir_all(&output).expect("create native build directory");
+        let mut generate = find_command("xcodegen");
+        generate.args([
+            "generate",
+            "--spec",
+            "platforms/macos/project.yml",
+            "--project",
+        ]);
+        generate.arg(&output);
+        run_command(generate);
+        let mut build = find_command("xcodebuild");
+        build.arg("-project").arg(output.join("YinYang.xcodeproj"));
+        build.args([
+            "-scheme",
+            "YinYang",
+            "-configuration",
+            "Debug",
+            "-derivedDataPath",
+        ]);
+        build.arg(output.join("DerivedData"));
+        build.args(["-destination", "platform=macOS", "build"]);
+        build.arg(format!("YINYANG_SOURCE_ROOT={}", root.display()));
+        build.arg(format!(
+            "YINYANG_NATIVE_LIBRARY={}",
+            target.join("debug/libyinyang_native.a").display()
+        ));
+        build.arg(format!(
+            "YINYANG_BRIDGING_HEADER={}",
+            root.join("crates/native/include/yinyang.h").display()
+        ));
+        if let Some(identity) = self.identity {
+            build.arg(format!("CODE_SIGN_IDENTITY={identity}"));
+            build.arg(format!(
+                "DEVELOPMENT_TEAM={}",
+                self.team.expect("team required")
+            ));
+            build.arg(format!(
+                "YINYANG_FSKIT_PROFILE={}",
+                self.fskit_profile.expect("profile required")
+            ));
+        } else {
+            build.arg("CODE_SIGNING_ALLOWED=NO");
+        }
+        run_command(build);
+    }
 }
 
 #[derive(Parser)]