@aigne/afs-json 1.11.0-beta.9 → 1.12.0-beta.5

package/README.md

@@ -304,3 +304,35 @@ Search for values within the JSON/YAML structure.
 - **Kubernetes Config**: Navigate and query YAML configuration files
 - **CI/CD Pipelines**: Access and modify YAML pipeline configurations
 
+
+## 选 provider 的判据：file-as-blob vs file-as-tree
+
+- **file-as-blob**（用 `AFSFS`）：内容是不透明字节流——README.md、二进制文件、用户上传文件等
+- **file-as-tree**（用 `AFSJSON` / `AFSToml` / `AFSYaml`）：内容是结构化数据，需要 sub-path 读写
+  单个字段。settings、config、provider 描述符等。
+
+判断口诀：**写一个字段时另一个字段会变吗？** 会 = 选 blob；不会 = 选 tree。
+Wrapper-format settings 永远是 tree。
+
+## Structured settings MUST mount via AFSJSON sub-path overlay
+
+任何 wrapper-format settings 文件（`{ label, description, value, ... }` 结构）**必须**通过 AFSJSON
+overlay mount 在自身路径上，让 bind 指向内层 sub-path（例如 `/<file>.json/value`），而不是直接写整个
+wrapper 文件。理由：
+
+- 直接写 wrapper 文件会丢失 sibling 字段（label / description）。这是 G0 回归 bug。
+- AFSJSON overlay 让每个 `{label, description, value}` 字段成为可读写的 primitive sub-path。
+  写 `/value` 只更新该字段，框架负责把整个 wrapper 重新序列化回磁盘——其他字段字节级保留。
+- `buildFlatSubMounts` 已自动检测 wrapper 结构并挂 overlay；新写代码 **不要**绕过它直接写
+  wrapper 文件路径。
+
+参考：`runtimes/node/src/program/structured-settings-overlay.ts`、回归 sentinel
+`providers/runtime/ui/test/persistence-sentinel.test.ts`、约定全文
+`providers/runtime/ui/docs/settings-persistence.md`。
+
+## Nested mount 用 `allowOverlay: true`
+
+在已经被一个 provider 覆盖的子路径下叠 overlay 时（典型场景：FS 已 mount `/instance` 后，要在
+`/instance/.../foo.json` 上叠 AFSJSON），mount 调用必须显式传 `{ allowOverlay: true }`，否则
+框架抛 `Mount conflict` 拒绝注册。验证要点：list 不重复、read 路由到 overlay、unmount
+后回退到底层 provider。参考 `providers/core/json/test/overlay.test.ts`。

package/dist/index.cjs

@@ -1,23 +1,36 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 const require_decorate = require('./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.cjs');
-let node_fs = require("node:fs");
-let node_fs_promises = require("node:fs/promises");
-let node_path = require("node:path");
+let node_crypto = require("node:crypto");
 let _aigne_afs = require("@aigne/afs");
 let _aigne_afs_provider = require("@aigne/afs/provider");
 let _aigne_afs_utils_zod = require("@aigne/afs/utils/zod");
+let _aigne_afs_provider_utils = require("@aigne/afs-provider-utils");
+let js_yaml = require("js-yaml");
 let ufo = require("ufo");
-let yaml = require("yaml");
 let zod = require("zod");
 
 //#region src/index.ts
 const LIST_MAX_LIMIT = 1e3;
+const JSON_AS_FORMATS = [
+	"content",
+	"compact",
+	"tree"
+];
 /** Hidden key for storing AFS metadata (mirrors FS provider's .afs directory) */
 const AFS_KEY = ".afs";
 /** Subkey for storing metadata (mirrors FS provider's meta.yaml file) */
 const META_KEY = "meta";
 /** Subkey for storing child node metadata (mirrors FS provider's .nodes directory) */
 const NODES_KEY = ".nodes";
+function assertLocalPathWithinCwd(resolvedPath, cwd, rawPath) {
+	const { path } = (0, _aigne_afs.getPlatform)();
+	const root = path.resolve(cwd);
+	const candidate = path.resolve(resolvedPath);
+	const rootPrefix = root.endsWith("/") || root.endsWith("\\") ? root : `${root}/`;
+	const windowsRootPrefix = root.endsWith("\\") ? root : `${root}\\`;
+	if (candidate !== root && !candidate.startsWith(rootPrefix) && !candidate.startsWith(windowsRootPrefix)) throw new Error(`Local path escapes configured base directory: ${rawPath}`);
+	return candidate;
+}
 const afsJSONOptionsSchema = (0, _aigne_afs_utils_zod.camelize)(zod.z.object({
 	name: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string()),
 	jsonPath: zod.z.string().describe("The path to the JSON/YAML file to mount"),
@@ -38,7 +51,7 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 	static manifest() {
 		return {
 			name: "json",
-			description: "Mount a JSON or YAML file as a virtual filesystem",
+			description: "JSON or YAML file — navigate and edit structured data as a tree.\n- Objects and arrays become directories, primitives become leaf nodes\n- Read/write individual values, search across structure\n- Path structure: `/{key}/{nested-key}` (arrays indexed by position)",
 			uriTemplate: "json://{localPath+}",
 			category: "structured-data",
 			schema: zod.z.object({ localPath: zod.z.string() }),
@@ -46,12 +59,56 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 				"json",
 				"yaml",
 				"structured-data"
-			]
+			],
+			capabilityTags: [
+				"read-write",
+				"crud",
+				"search",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "sandboxed",
+				resourceAccess: []
+			},
+			capabilities: { filesystem: {
+				read: true,
+				write: true
+			} }
+		};
+	}
+	static treeSchema() {
+		return {
+			operations: [
+				"list",
+				"read",
+				"write",
+				"delete",
+				"search",
+				"stat",
+				"explain"
+			],
+			tree: {
+				"/": { kind: "json:root" },
+				"/{key}": { kind: "json:value" }
+			},
+			auth: { type: "none" },
+			bestFor: [
+				"JSON/YAML navigation",
+				"structured data editing",
+				"config files"
+			],
+			notFor: ["binary files", "large datasets"]
 		};
 	}
 	static async load({ basePath, config } = {}) {
+		const raw = config;
+		const normalized = raw?.localPath && !raw.jsonPath ? {
+			...raw,
+			jsonPath: raw.localPath
+		} : raw;
 		return new AFSJSON({
-			...await AFSJSON.schema().parseAsync(config),
+			...await AFSJSON.schema().parseAsync(normalized),
 			cwd: basePath
 		});
 	}
@@ -68,22 +125,17 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		this.options = options;
 		if (options.localPath && !options.jsonPath) options.jsonPath = options.localPath;
 		(0, _aigne_afs_utils_zod.zodParse)(afsJSONOptionsSchema, options);
-		let jsonPath;
-		jsonPath = options.jsonPath.replaceAll("${CWD}", process.cwd());
-		if (jsonPath.startsWith("~/")) jsonPath = (0, node_path.join)(process.env.HOME || "", jsonPath.slice(2));
-		if (!(0, node_path.isAbsolute)(jsonPath)) jsonPath = (0, node_path.join)(options.cwd || process.cwd(), jsonPath);
-		if (!(0, node_fs.existsSync)(jsonPath)) {
-			(0, node_fs.mkdirSync)((0, node_path.dirname)(jsonPath), { recursive: true });
-			(0, node_fs.writeFileSync)(jsonPath, "{}", "utf8");
-		}
-		const ext = (0, node_path.extname)(jsonPath).toLowerCase();
+		let jsonPath = (0, _aigne_afs_provider_utils.resolveLocalPath)(options.jsonPath, { cwd: options.cwd });
+		if (options.cwd) jsonPath = assertLocalPathWithinCwd(jsonPath, options.cwd, options.jsonPath);
+		const platform = (0, _aigne_afs.getPlatform)();
+		const ext = platform.path.extname(jsonPath).toLowerCase();
 		this.fileFormat = ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
 		const extensions = [
 			".json",
 			".yaml",
 			".yml"
 		];
-		let name = (0, node_path.basename)(jsonPath);
+		let name = platform.path.basename(jsonPath);
 		for (const e of extensions) if (name.endsWith(e)) {
 			name = name.slice(0, -e.length);
 			break;
@@ -94,6 +146,12 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		this.accessMode = options.accessMode ?? (options.agentSkills ? "readonly" : "readwrite");
 		this.resolvedJsonPath = jsonPath;
 	}
+	async supportedAs(path) {
+		await this.ensureLoaded();
+		const normalizedPath = this.normalizePath(path);
+		const segments = this.getPathSegments(normalizedPath);
+		return this.getValueAtPath(this.jsonData, segments) === void 0 ? [] : [...JSON_AS_FORMATS];
+	}
 	/**
 	* Read metadata for a JSON node via /.meta or /path/.meta
 	* Returns stored metadata merged with computed type information
@@ -145,7 +203,17 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		if (!this.isDirectoryValue(value)) return { data: [] };
 		const entries = [];
 		const rootChildren = this.getChildren(value);
-		const queue = (rootChildren.length > maxChildren ? rootChildren.slice(0, maxChildren) : rootChildren).map((child) => ({
+		const rootChildrenToProcess = rootChildren.length > maxChildren ? rootChildren.slice(0, maxChildren) : rootChildren;
+		const orderBy = ctx.options?.orderBy;
+		if (maxDepth === 1 && (0, _aigne_afs.orderByRequested)(orderBy)) {
+			const { entries: ordered, applied } = (0, _aigne_afs.orderEntries)(rootChildrenToProcess.map((child) => this.valueToAFSEntry(normalizedPath === "/" ? `/${child.key}` : `${normalizedPath}/${child.key}`, child.value)), orderBy);
+			const data = ordered.slice(0, limit);
+			return applied ? { data } : {
+				data,
+				meta: { orderByIgnored: true }
+			};
+		}
+		const queue = rootChildrenToProcess.map((child) => ({
 			path: normalizedPath === "/" ? `/${child.key}` : `${normalizedPath}/${child.key}`,
 			value: child.value,
 			depth: 1
@@ -170,14 +238,37 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 				}
 			}
 		}
+		if ((0, _aigne_afs.orderByRequested)(orderBy)) return {
+			data: entries,
+			meta: { orderByIgnored: true }
+		};
 		return { data: entries };
 	}
+	/**
+	* AFSJSON handles `handleDepth` itself, so it doesn't get the base.ts
+	* orderBy fallback — it implements ordering natively in listHandler and
+	* declares the sub-capability here (consumed by both base.list's
+	* no-silent-drop check and the /.meta/.capabilities manifest).
+	*/
+	getOperationsDeclaration() {
+		const ops = super.getOperationsDeclaration();
+		if (typeof ops.list === "boolean" ? ops.list : ops.list?.supported === true) ops.list = {
+			supported: true,
+			features: { orderBy: true }
+		};
+		return ops;
+	}
 	async readHandler(ctx) {
 		await this.ensureLoaded();
 		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
 		const segments = this.getPathSegments(normalizedPath);
 		const value = this.getValueAtPath(this.jsonData, segments);
 		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		const as = ctx.options?.as;
+		if (as) {
+			if (!this.isJsonAsFormat(as)) throw new _aigne_afs.AFSNotFoundError((0, ufo.joinURL)(normalizedPath, ".as", as));
+			return this.buildJsonAsEntry(normalizedPath, value, as);
+		}
 		return this.valueToAFSEntry(normalizedPath, value);
 	}
 	/**
@@ -193,6 +284,15 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		await this.ensureLoaded();
 		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
 		const segments = this.getPathSegments(normalizedPath);
+		const ifMatch = ctx.options?.ifMatch;
+		if (ifMatch !== void 0) {
+			const currentValue = this.getValueAtPath(this.jsonData, segments);
+			const currentVersion = this.computeVersion(currentValue);
+			if (ifMatch !== currentVersion) throw new _aigne_afs.AFSConflictError(normalizedPath, {
+				cid: currentVersion,
+				mtime: this.fileStats.mtime ? this.fileStats.mtime.getTime() : null
+			});
+		}
 		if (payload.content !== void 0) this.setValueAtPath(this.jsonData, segments, payload.content);
 		if (payload.meta !== void 0 && typeof payload.meta === "object") {
 			const finalMeta = {
@@ -215,7 +315,8 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 			updatedAt: this.fileStats.mtime,
 			meta: {
 				...storedMeta,
-				childrenCount: isDir ? children.length : void 0
+				childrenCount: isDir ? children.length : void 0,
+				version: this.computeVersion(newValue)
 			},
 			userId: payload.userId,
 			sessionId: payload.sessionId,
@@ -291,6 +392,7 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		const children = isDir ? this.getChildren(value) : [];
 		const meta = { ...this.loadMeta(normalizedPath) };
 		if (isDir) meta.childrenCount = children.length;
+		meta.version = this.computeVersion(value);
 		return { data: {
 			id: segments.length > 0 ? segments[segments.length - 1] : "/",
 			path: normalizedPath,
@@ -299,6 +401,16 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 			meta
 		} };
 	}
+	/**
+	* Compute an opaque version string for a JSON value at a given path.
+	* Used as the ifMatch token for optimistic-concurrency writes. SHA-256 over
+	* the canonical JSON serialization keeps the token stable across mounts of
+	* the same content. Clients treat this as opaque — see AFSWriteOptions.ifMatch.
+	*/
+	computeVersion(value) {
+		const canonical = value === void 0 ? "\0undefined" : JSON.stringify(value) ?? "null";
+		return (0, node_crypto.createHash)("sha256").update(canonical).digest("hex");
+	}
 	async readCapabilitiesHandler(_ctx) {
 		await this.ensureLoaded();
 		const operations = [
@@ -309,6 +421,11 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 			"search"
 		];
 		if (this.accessMode === "readwrite") operations.push("write", "delete", "rename");
+		const baseOps = this.getOperationsDeclaration();
+		if (typeof baseOps.write === "boolean" ? baseOps.write : baseOps.write?.supported === true) baseOps.write = {
+			supported: true,
+			features: { ifMatch: true }
+		};
 		return {
 			id: "/.meta/.capabilities",
 			path: "/.meta/.capabilities",
@@ -318,7 +435,7 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 				description: this.description || `JSON/YAML virtual filesystem (${this.fileFormat} format)`,
 				tools: [],
 				actions: [],
-				operations: this.getOperationsDeclaration()
+				operations: baseOps
 			},
 			meta: {
 				kind: "afs:capabilities",
@@ -492,16 +609,20 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 	*/
 	async ensureLoaded() {
 		if (this.jsonData !== null) return;
+		const platform = (0, _aigne_afs.getPlatform)();
 		try {
-			const stats = await (0, node_fs_promises.stat)(this.resolvedJsonPath);
+			const stats = await platform.fs.stat(this.resolvedJsonPath);
 			this.fileStats = {
-				birthtime: stats.birthtime,
-				mtime: stats.mtime
+				birthtime: stats.birthtime ? new Date(stats.birthtime) : void 0,
+				mtime: stats.mtime ? new Date(stats.mtime) : void 0
 			};
-			this.jsonData = (0, yaml.parse)(await (0, node_fs_promises.readFile)(this.resolvedJsonPath, "utf8"));
-		} catch (error) {
-			if (error.code === "ENOENT") this.jsonData = {};
-			else throw error;
+			this.jsonData = (0, js_yaml.load)(await platform.fs.readTextFile(this.resolvedJsonPath));
+		} catch {
+			try {
+				await platform.fs.mkdir(platform.path.dirname(this.resolvedJsonPath), { recursive: true });
+				await platform.fs.writeFile(this.resolvedJsonPath, "{}");
+			} catch {}
+			this.jsonData = {};
 		}
 	}
 	/**
@@ -509,22 +630,34 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 	*/
 	async saveToFile() {
 		let content;
-		if (this.fileFormat === "yaml") content = (0, yaml.stringify)(this.jsonData);
+		if (this.fileFormat === "yaml") content = (0, js_yaml.dump)(this.jsonData);
 		else content = JSON.stringify(this.jsonData, null, 2);
-		await (0, node_fs_promises.writeFile)(this.resolvedJsonPath, content, "utf8");
-		const stats = await (0, node_fs_promises.stat)(this.resolvedJsonPath);
+		const platform = (0, _aigne_afs.getPlatform)();
+		await platform.fs.writeFile(this.resolvedJsonPath, content);
+		const stats = await platform.fs.stat(this.resolvedJsonPath);
 		this.fileStats = {
-			birthtime: this.fileStats.birthtime || stats.birthtime,
-			mtime: stats.mtime
+			birthtime: this.fileStats.birthtime,
+			mtime: stats.mtime ? new Date(stats.mtime) : void 0
 		};
 	}
 	/**
 	* Get path segments from normalized path
 	*/
+	/**
+	* Dangerous property names that must never be used as object keys.
+	* Prevents prototype pollution attacks (e.g., writing to /__proto__/polluted).
+	*/
+	static DANGEROUS_KEYS = new Set([
+		"__proto__",
+		"constructor",
+		"prototype"
+	]);
 	getPathSegments(path) {
 		const normalized = this.normalizePath(path);
 		if (normalized === "/") return [];
-		return normalized.slice(1).split("/");
+		const segments = normalized.slice(1).split("/");
+		for (const segment of segments) if (AFSJSON.DANGEROUS_KEYS.has(segment)) throw new Error(`Path segment "${segment}" is not allowed (prototype pollution guard)`);
+		return segments;
 	}
 	/**
 	* Navigate to a value in the JSON structure using path segments
@@ -609,6 +742,9 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		if (typeof value === "object" && value !== null) return true;
 		return false;
 	}
+	isJsonAsFormat(value) {
+		return typeof value === "string" && JSON_AS_FORMATS.includes(value);
+	}
 	/**
 	* Get children of a directory value (filters out .afs meta key)
 	*/
@@ -623,6 +759,48 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 		}));
 		return [];
 	}
+	compactJsonValue(value) {
+		if (!this.isDirectoryValue(value)) return value;
+		if (Array.isArray(value)) return {
+			type: "array",
+			length: value.length,
+			sample: value.slice(0, 3).map((item) => this.compactJsonValue(item))
+		};
+		const entries = Object.entries(value).filter(([key]) => !this.isMetaKey(key));
+		const preview = {};
+		for (const [key, child] of entries) {
+			if (Object.keys(preview).length >= 6) break;
+			if (!this.isDirectoryValue(child)) preview[key] = child;
+		}
+		return {
+			type: "object",
+			keys: entries.map(([key]) => key).slice(0, 12),
+			...Object.keys(preview).length > 0 ? { preview } : {}
+		};
+	}
+	stripMetaFromValue(value) {
+		if (!this.isDirectoryValue(value)) return value;
+		if (Array.isArray(value)) return value.map((item) => this.stripMetaFromValue(item));
+		const result = {};
+		for (const [key, child] of Object.entries(value)) if (!this.isMetaKey(key)) result[key] = this.stripMetaFromValue(child);
+		return result;
+	}
+	buildJsonAsEntry(path, value, as) {
+		let content;
+		if (as === "content") content = value;
+		else if (as === "tree") content = this.stripMetaFromValue(value);
+		else content = this.compactJsonValue(value);
+		return {
+			id: `${path}.as:${as}`,
+			path: (0, ufo.joinURL)(path, ".as", as),
+			content,
+			meta: {
+				kind: `json:${as}`,
+				representation: as
+			},
+			actions: []
+		};
+	}
 	/**
 	* Convert a JSON value to an AFSEntry
 	*/
@@ -634,7 +812,8 @@ var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 			content: isDir ? void 0 : value,
 			meta: {
 				kind,
-				childrenCount: isDir ? children.length : void 0
+				childrenCount: isDir ? children.length : void 0,
+				version: this.computeVersion(value)
 			},
 			createdAt: this.fileStats.birthtime,
 			updatedAt: this.fileStats.mtime

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AFSAccessMode, AFSEntry, AFSExplainResult, AFSListResult, AFSModuleLoadParams, AFSSearchOptions, AFSStatResult, AFSWriteEntryPayload, ProviderManifest } from "@aigne/afs";
+import { AFSAccessMode, AFSEntry, AFSExplainResult, AFSListResult, AFSModuleLoadParams, AFSSearchOptions, AFSStatResult, AFSWriteEntryPayload, OperationsDeclaration, ProviderManifest, ProviderTreeSchema } from "@aigne/afs";
 import { AFSBaseProvider, RouteContext } from "@aigne/afs/provider";
 import { z } from "zod";
 
@@ -47,6 +47,7 @@ declare class AFSJSON extends AFSBaseProvider {
     agentSkills: boolean | undefined;
   }, unknown>>;
   static manifest(): ProviderManifest;
+  static treeSchema(): ProviderTreeSchema;
   static load({
     basePath,
     config
@@ -64,6 +65,7 @@ declare class AFSJSON extends AFSBaseProvider {
     localPath?: string;
     uri?: string;
   });
+  supportedAs(path: string): Promise<string[]>;
   /**
    * Read metadata for a JSON node via /.meta or /path/.meta
    * Returns stored metadata merged with computed type information
@@ -77,6 +79,13 @@ declare class AFSJSON extends AFSBaseProvider {
   }>): Promise<AFSListResult & {
     noExpand?: string[];
   }>;
+  /**
+   * AFSJSON handles `handleDepth` itself, so it doesn't get the base.ts
+   * orderBy fallback — it implements ordering natively in listHandler and
+   * declares the sub-capability here (consumed by both base.list's
+   * no-silent-drop check and the /.meta/.capabilities manifest).
+   */
+  protected getOperationsDeclaration(): OperationsDeclaration;
   readHandler(ctx: RouteContext<{
     path?: string;
   }>): Promise<AFSEntry | undefined>;
@@ -113,6 +122,13 @@ declare class AFSJSON extends AFSBaseProvider {
   statHandler(ctx: RouteContext<{
     path?: string;
   }>): Promise<AFSStatResult>;
+  /**
+   * Compute an opaque version string for a JSON value at a given path.
+   * Used as the ifMatch token for optimistic-concurrency writes. SHA-256 over
+   * the canonical JSON serialization keeps the token stable across mounts of
+   * the same content. Clients treat this as opaque — see AFSWriteOptions.ifMatch.
+   */
+  private computeVersion;
   readCapabilitiesHandler(_ctx: RouteContext): Promise<AFSEntry | undefined>;
   explainHandler(ctx: RouteContext<{
     path?: string;
@@ -153,6 +169,11 @@ declare class AFSJSON extends AFSBaseProvider {
   /**
    * Get path segments from normalized path
    */
+  /**
+   * Dangerous property names that must never be used as object keys.
+   * Prevents prototype pollution attacks (e.g., writing to /__proto__/polluted).
+   */
+  private static readonly DANGEROUS_KEYS;
   private getPathSegments;
   /**
    * Navigate to a value in the JSON structure using path segments
@@ -170,10 +191,14 @@ declare class AFSJSON extends AFSBaseProvider {
    * Check if a value is a "directory" (object or array with children)
    */
   private isDirectoryValue;
+  private isJsonAsFormat;
   /**
    * Get children of a directory value (filters out .afs meta key)
    */
   private getChildren;
+  private compactJsonValue;
+  private stripMetaFromValue;
+  private buildJsonAsEntry;
   /**
    * Convert a JSON value to an AFSEntry
    */

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UAkDiB,cAAA;EACf,IAAA;EACA,QAAA;EACA,WAAA;;;;;;;EAOA,UAAA,GAAa,aAAA;EAMb;;;AAuBF;;EAvBE,WAAA;AAAA;;;;;;;cAuBW,OAAA,SAAgB,eAAA;EAkCR,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAAA,OAjC1E,MAAA,CAAA,GAAM,CAAA,CAAA,OAAA;;;;;;;;;;;;;SAIN,QAAA,CAAA,GAAY,gBAAA;EAAA,OAWN,IAAA,CAAA;IAAO,QAAA;IAAU;EAAA,IAAU,mBAAA,GAAwB,OAAA,CAAA,OAAA;EAAA,SAKvD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA,EAAY,aAAA;EAAA,SACZ,WAAA;EAAA,QAED,QAAA;EAAA,QACA,SAAA;EAAA,QAIA,UAAA;EAAA,QACA,gBAAA;cAEW,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAlCtD;;;;;EA4GrB,eAAA,CAAgB,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;EAmE/D,WAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KACnB,OAAA,CAAQ,aAAA;IAAkB,QAAA;EAAA;EAiFvB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;;;;;;;;;;EAwB3D,YAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,EAAS,oBAAA,GACR,OAAA;IAAU,IAAA,EAAM,QAAA;EAAA;EAgDb,aAAA,CAAc,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA;IAAU,OAAA;EAAA;EA0B/D,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,WACC,OAAA;IAAU,OAAA;EAAA;EAiCP,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,KAAA,UACA,OAAA,GAAU,gBAAA,GACT,OAAA;IAAU,IAAA,EAAM,QAAA;IAAY,OAAA;EAAA;EAuDzB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,aAAA;EAmC3D,uBAAA,CAAwB,IAAA,EAAM,YAAA,GAAe,OAAA,CAAQ,QAAA;EA0BrD,cAAA,CAAe,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,gBAAA;EAvZ9C;;;EAAA,QAmgBd,YAAA;EA/bD;;;EAAA,QA8cC,SAAA;EA7cG;;;;;;;EAAA,QAwdH,QAAA;EA/WF;;;;;;;EAAA,QA+aE,QAAA;EA5aW;;;;EAAA,QAseL,YAAA;EAtb6C;;;EAAA,QAid7C,UAAA;EAtbQ;;;EAAA,QA6cd,eAAA;EA3cK;;;EAAA,QAodL,cAAA;EAlbN;;;EAAA,QA0cM,cAAA;EAvcL;;;EAAA,QAigBK,iBAAA;EA1cF;;;EAAA,QAqfE,gBAAA;EArfiD;;;EAAA,QA8fjD,WAAA;EA3dsB;;;EAAA,QA0etB,eAAA;AAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UA2EiB,cAAA;EACf,IAAA;EACA,QAAA;EACA,WAAA;;;;;;;EAOA,UAAA,GAAa,aAAA;EAMb;;;AAuBF;;EAvBE,WAAA;AAAA;;;;;;;cAuBW,OAAA,SAAgB,eAAA;EA0DR,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAAA,OAzD1E,MAAA,CAAA,GAAM,CAAA,CAAA,OAAA;;;;;;;;;;;;;SAIN,QAAA,CAAA,GAAY,gBAAA;EAAA,OAoBZ,UAAA,CAAA,GAAc,kBAAA;EAAA,OAaR,IAAA,CAAA;IAAO,QAAA;IAAU;EAAA,IAAU,mBAAA,GAAwB,OAAA,CAAA,OAAA;EAAA,SAOvD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA,EAAY,aAAA;EAAA,SACZ,WAAA;EAAA,QAED,QAAA;EAAA,QACA,SAAA;EAAA,QAIA,UAAA;EAAA,QACA,gBAAA;cAEW,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAwC3E,WAAA,CAAY,IAAA,WAAe,OAAA;EAyhB2B;;;;;EAvftD,eAAA,CAAgB,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;EAmE/D,WAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KACnB,OAAA,CAAQ,aAAA;IAAkB,QAAA;EAAA;;;;;;;YA8GnB,wBAAA,CAAA,GAA4B,qBAAA;EAUhC,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;;;;;;;;;;EA8B3D,YAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,EAAS,oBAAA,GACR,OAAA;IAAU,IAAA,EAAM,QAAA;EAAA;EAiEb,aAAA,CAAc,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA;IAAU,OAAA;EAAA;EA0B/D,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,WACC,OAAA;IAAU,OAAA;EAAA;EAiCP,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,KAAA,UACA,OAAA,GAAU,gBAAA,GACT,OAAA;IAAU,IAAA,EAAM,QAAA;IAAY,OAAA;EAAA;EAuDzB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,aAAA;EAxZ3D;;;;;;EAAA,QAkcE,cAAA;EAQF,uBAAA,CAAwB,IAAA,EAAM,YAAA,GAAe,OAAA,CAAQ,QAAA;EA6CrD,cAAA,CAAe,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,gBAAA;EAlbzD;;;EAAA,QA8hBH,YAAA;EAtaF;;;EAAA,QAqbE,SAAA;EArbiD;;;;;;;EAAA,QAgcjD,QAAA;EA/ZL;;;;;;;EAAA,QA+dK,QAAA;EA9Z6D;;;;EAAA,QAwdvD,YAAA;EA5bZ;;;EAAA,QA4dY,UAAA;EAzbP;;;EACL;;;;EAAA,wBAodsB,cAAA;EAAA,QAEhB,eAAA;EApduB;;;EAAA,QAsevB,cAAA;EA/aU;;;EAAA,QAucV,cAAA;EArZF;;;EAAA,QA+cE,iBAAA;EA/cmD;;;EAAA,QA0fnD,gBAAA;EAAA,QAMA,cAAA;EAndoD;;;EAAA,QA0dpD,WAAA;EAAA,QAYA,gBAAA;EAAA,QAwBA,kBAAA;EAAA,QAUA,gBAAA;EAxOM;;;EAAA,QA4PN,eAAA;AAAA"}

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AFSAccessMode, AFSEntry, AFSExplainResult, AFSListResult, AFSModuleLoadParams, AFSSearchOptions, AFSStatResult, AFSWriteEntryPayload, ProviderManifest } from "@aigne/afs";
+import { AFSAccessMode, AFSEntry, AFSExplainResult, AFSListResult, AFSModuleLoadParams, AFSSearchOptions, AFSStatResult, AFSWriteEntryPayload, OperationsDeclaration, ProviderManifest, ProviderTreeSchema } from "@aigne/afs";
 import { AFSBaseProvider, RouteContext } from "@aigne/afs/provider";
 import { z } from "zod";
 
@@ -47,6 +47,7 @@ declare class AFSJSON extends AFSBaseProvider {
     agentSkills: boolean | undefined;
   }, unknown>>;
   static manifest(): ProviderManifest;
+  static treeSchema(): ProviderTreeSchema;
   static load({
     basePath,
     config
@@ -64,6 +65,7 @@ declare class AFSJSON extends AFSBaseProvider {
     localPath?: string;
     uri?: string;
   });
+  supportedAs(path: string): Promise<string[]>;
   /**
    * Read metadata for a JSON node via /.meta or /path/.meta
    * Returns stored metadata merged with computed type information
@@ -77,6 +79,13 @@ declare class AFSJSON extends AFSBaseProvider {
   }>): Promise<AFSListResult & {
     noExpand?: string[];
   }>;
+  /**
+   * AFSJSON handles `handleDepth` itself, so it doesn't get the base.ts
+   * orderBy fallback — it implements ordering natively in listHandler and
+   * declares the sub-capability here (consumed by both base.list's
+   * no-silent-drop check and the /.meta/.capabilities manifest).
+   */
+  protected getOperationsDeclaration(): OperationsDeclaration;
   readHandler(ctx: RouteContext<{
     path?: string;
   }>): Promise<AFSEntry | undefined>;
@@ -113,6 +122,13 @@ declare class AFSJSON extends AFSBaseProvider {
   statHandler(ctx: RouteContext<{
     path?: string;
   }>): Promise<AFSStatResult>;
+  /**
+   * Compute an opaque version string for a JSON value at a given path.
+   * Used as the ifMatch token for optimistic-concurrency writes. SHA-256 over
+   * the canonical JSON serialization keeps the token stable across mounts of
+   * the same content. Clients treat this as opaque — see AFSWriteOptions.ifMatch.
+   */
+  private computeVersion;
   readCapabilitiesHandler(_ctx: RouteContext): Promise<AFSEntry | undefined>;
   explainHandler(ctx: RouteContext<{
     path?: string;
@@ -153,6 +169,11 @@ declare class AFSJSON extends AFSBaseProvider {
   /**
    * Get path segments from normalized path
    */
+  /**
+   * Dangerous property names that must never be used as object keys.
+   * Prevents prototype pollution attacks (e.g., writing to /__proto__/polluted).
+   */
+  private static readonly DANGEROUS_KEYS;
   private getPathSegments;
   /**
    * Navigate to a value in the JSON structure using path segments
@@ -170,10 +191,14 @@ declare class AFSJSON extends AFSBaseProvider {
    * Check if a value is a "directory" (object or array with children)
    */
   private isDirectoryValue;
+  private isJsonAsFormat;
   /**
    * Get children of a directory value (filters out .afs meta key)
    */
   private getChildren;
+  private compactJsonValue;
+  private stripMetaFromValue;
+  private buildJsonAsEntry;
   /**
    * Convert a JSON value to an AFSEntry
    */

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UAkDiB,cAAA;EACf,IAAA;EACA,QAAA;EACA,WAAA;;;;;;;EAOA,UAAA,GAAa,aAAA;EAMb;;;AAuBF;;EAvBE,WAAA;AAAA;;;;;;;cAuBW,OAAA,SAAgB,eAAA;EAkCR,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAAA,OAjC1E,MAAA,CAAA,GAAM,CAAA,CAAA,OAAA;;;;;;;;;;;;;SAIN,QAAA,CAAA,GAAY,gBAAA;EAAA,OAWN,IAAA,CAAA;IAAO,QAAA;IAAU;EAAA,IAAU,mBAAA,GAAwB,OAAA,CAAA,OAAA;EAAA,SAKvD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA,EAAY,aAAA;EAAA,SACZ,WAAA;EAAA,QAED,QAAA;EAAA,QACA,SAAA;EAAA,QAIA,UAAA;EAAA,QACA,gBAAA;cAEW,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAlCtD;;;;;EA4GrB,eAAA,CAAgB,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;EAmE/D,WAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KACnB,OAAA,CAAQ,aAAA;IAAkB,QAAA;EAAA;EAiFvB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;;;;;;;;;;EAwB3D,YAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,EAAS,oBAAA,GACR,OAAA;IAAU,IAAA,EAAM,QAAA;EAAA;EAgDb,aAAA,CAAc,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA;IAAU,OAAA;EAAA;EA0B/D,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,WACC,OAAA;IAAU,OAAA;EAAA;EAiCP,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,KAAA,UACA,OAAA,GAAU,gBAAA,GACT,OAAA;IAAU,IAAA,EAAM,QAAA;IAAY,OAAA;EAAA;EAuDzB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,aAAA;EAmC3D,uBAAA,CAAwB,IAAA,EAAM,YAAA,GAAe,OAAA,CAAQ,QAAA;EA0BrD,cAAA,CAAe,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,gBAAA;EAvZ9C;;;EAAA,QAmgBd,YAAA;EA/bD;;;EAAA,QA8cC,SAAA;EA7cG;;;;;;;EAAA,QAwdH,QAAA;EA/WF;;;;;;;EAAA,QA+aE,QAAA;EA5aW;;;;EAAA,QAseL,YAAA;EAtb6C;;;EAAA,QAid7C,UAAA;EAtbQ;;;EAAA,QA6cd,eAAA;EA3cK;;;EAAA,QAodL,cAAA;EAlbN;;;EAAA,QA0cM,cAAA;EAvcL;;;EAAA,QAigBK,iBAAA;EA1cF;;;EAAA,QAqfE,gBAAA;EArfiD;;;EAAA,QA8fjD,WAAA;EA3dsB;;;EAAA,QA0etB,eAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UA2EiB,cAAA;EACf,IAAA;EACA,QAAA;EACA,WAAA;;;;;;;EAOA,UAAA,GAAa,aAAA;EAMb;;;AAuBF;;EAvBE,WAAA;AAAA;;;;;;;cAuBW,OAAA,SAAgB,eAAA;EA0DR,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAAA,OAzD1E,MAAA,CAAA,GAAM,CAAA,CAAA,OAAA;;;;;;;;;;;;;SAIN,QAAA,CAAA,GAAY,gBAAA;EAAA,OAoBZ,UAAA,CAAA,GAAc,kBAAA;EAAA,OAaR,IAAA,CAAA;IAAO,QAAA;IAAU;EAAA,IAAU,mBAAA,GAAwB,OAAA,CAAA,OAAA;EAAA,SAOvD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA,EAAY,aAAA;EAAA,SACZ,WAAA;EAAA,QAED,QAAA;EAAA,QACA,SAAA;EAAA,QAIA,UAAA;EAAA,QACA,gBAAA;cAEW,OAAA,EAAS,cAAA;IAAmB,GAAA;IAAc,SAAA;IAAoB,GAAA;EAAA;EAwC3E,WAAA,CAAY,IAAA,WAAe,OAAA;EAyhB2B;;;;;EAvftD,eAAA,CAAgB,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;EAmE/D,WAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KACnB,OAAA,CAAQ,aAAA;IAAkB,QAAA;EAAA;;;;;;;YA8GnB,wBAAA,CAAA,GAA4B,qBAAA;EAUhC,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,QAAA;;;;;;;;;;EA8B3D,YAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,EAAS,oBAAA,GACR,OAAA;IAAU,IAAA,EAAM,QAAA;EAAA;EAiEb,aAAA,CAAc,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA;IAAU,OAAA;EAAA;EA0B/D,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,OAAA,WACC,OAAA;IAAU,OAAA;EAAA;EAiCP,aAAA,CACJ,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,IACpB,KAAA,UACA,OAAA,GAAU,gBAAA,GACT,OAAA;IAAU,IAAA,EAAM,QAAA;IAAY,OAAA;EAAA;EAuDzB,WAAA,CAAY,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,aAAA;EAxZ3D;;;;;;EAAA,QAkcE,cAAA;EAQF,uBAAA,CAAwB,IAAA,EAAM,YAAA,GAAe,OAAA,CAAQ,QAAA;EA6CrD,cAAA,CAAe,GAAA,EAAK,YAAA;IAAe,IAAA;EAAA,KAAmB,OAAA,CAAQ,gBAAA;EAlbzD;;;EAAA,QA8hBH,YAAA;EAtaF;;;EAAA,QAqbE,SAAA;EArbiD;;;;;;;EAAA,QAgcjD,QAAA;EA/ZL;;;;;;;EAAA,QA+dK,QAAA;EA9Z6D;;;;EAAA,QAwdvD,YAAA;EA5bZ;;;EAAA,QA4dY,UAAA;EAzbP;;;EACL;;;;EAAA,wBAodsB,cAAA;EAAA,QAEhB,eAAA;EApduB;;;EAAA,QAsevB,cAAA;EA/aU;;;EAAA,QAucV,cAAA;EArZF;;;EAAA,QA+cE,iBAAA;EA/cmD;;;EAAA,QA0fnD,gBAAA;EAAA,QAMA,cAAA;EAndoD;;;EAAA,QA0dpD,WAAA;EAAA,QAYA,gBAAA;EAAA,QAwBA,kBAAA;EAAA,QAUA,gBAAA;EAxOM;;;EAAA,QA4PN,eAAA;AAAA"}