@aigne/afs-did-space 1.12.0-beta.5

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,129 @@
+# @aigne/afs-did-space
+
+DID-scoped 持久化存储 provider。一个 DID 对应一个 DID Space；service 在用户 DID Space 中只占一段 path 前缀。
+
+## 三条不变约束（new code / new design must respect）
+
+1. **DID Space 是 AFS first-class mount**
+   不是 REST 服务。`DIDSpaceProvider` 实现完整 AFS provider 协议（`@List/@Read/@Write/@Delete/@Stat/@Search/@Explain`），可以被 `afs.mount()`。Transport 可插拔（local FS / Cloudflare D1+R2 / WebSocket / HTTP / static read-only / in-memory）。
+
+2. **Hosting 后端可插拔**
+   DID Space 主要承载 mutable runtime data（instance system + user data）；也可以承载 immutable artifact（如 blocklet 代码——通过 `.share` 暴露 readonly URL）。ARC 不 care artifact host 在哪——pages.dev / S3 / DID Space share / 任何 AFS-compatible readonly endpoint 都行。CDN 是当前生产 default，**不是架构铁律**。
+
+3. **一个 user = 一个 DID Space**
+   Service 在用户 DID Space 中只是 path 前缀。路径布局：
+   ```
+   {principalDid}/blocklets/{instance-did}/system/...   ← installer / instance-owned content
+   {principalDid}/blocklets/{instance-did}/user/...     ← 该 principal 作为 caller 的 user-owned content
+   {principalDid}/blocklets/{instance-did}/config/mounts.toml   ← runtime-internal config fragment
+   ```
+   role 片段的内容树直接在 role 根；没有 `files/` 包装层，也没有 role-local `vault/` 片段（真实 vault 由 `@aigne/afs-vault` provider 承载）。`config/` 是 provider 内部 sibling，不出现在 blocklet 的 `/instance` 视图里。
+   同一个 principal 的 `system/` 与 `user/` 只是同一 DID Space 的两个 path-prefix view；installer 与真实 caller 可以由 `SpaceResolver` 选到不同 principal 的 DID Space。
+
+> 概念权威见 [`docs/architecture/did-space.md`](../../../docs/architecture/did-space.md)；活计划见 [`planning/did-integration/did-space-alignment/`](../../../planning/did-integration/did-space-alignment/)。
+
+## 同步 transport：afs-rpc（mobile）+ 内容寻址后端（two-runtime 统一）
+
+`mobile-didspace-transport` 计划（2026-06）把 DID Space sync 统一到两条不变量上：
+
+1. **单一 transport = `POST /api/afs/rpc`**（共享 `createAfsRpcHandler @aigne/aos`，Node +
+   Cloudflare 同一份）。移动端 `RemoteDIDSpaceAFS`（Swift/Kotlin）用纯标准 AFS op
+   （list/read/stat/write/delete）同步——零私有 REST、读写对称。
+   - 鉴权：`Authorization: Bearer <login_token>`（写**必须** Bearer，cookie-only 写拒，防 CSRF）。
+   - 写面 allowlist：只允许已认证 caller 写**自己**的 `/user/**` 数据路径；`/instance`、`/space`、
+     root-scope、`.objects`/`.changelog` 虚拟路径一律拒。
+   - 字段位置：write `ifMatch` 走 `options.ifMatch`（顶层），`deviceId`/`mtime` 走 `options.meta`；
+     delete 三字段都在 `options.meta`。content 用 base64；`.objects/{cid}` 读后 client recompute CID 校验。
+   - 冲突：`AFS_CONFLICT` → HTTP 409（+ currentCid/mtime/deviceId）。超限：> 16MB → 413（旁路 deferred）。
+   - 契约权威：[`planning/did-integration/mobile-didspace-transport/wire-contract.md`](../../../planning/did-integration/mobile-didspace-transport/wire-contract.md)。
+
+2. **单一 `DIDSpaceProvider`，两端只换注入的存储原语**：
+   - Cloudflare：`objectStore = R2`（按 user space 前缀 key 隔离）+ `treeIndex = D1TreeIndex`。
+   - Node：`objectStore = FsObjectStore`（`{userDir}/objects/{cid}`）+ `treeIndex = SQLiteTreeIndex`
+     （over `MetadataDB` libsql，与 `D1TreeIndex` 共享 `changelog-schema.ts` DDL + 同一 conformance suite）。
+   Node 后端因此从「裸 AFSFS verbatim 树」升级为**内容寻址**：`.objects/{cid}`、`.changelog`
+   增量、`maxDepth:-1` manifest、device-aware 写、ifMatch 全部可用。物理布局 = `objects/{cid}` +
+   `_metadata.db`（索引即 SoT），**不再有** verbatim 文件树。
+
+mobile sync 把 aside app 建模为一个 blocklet，数据 = caller 的 `blocklets/<aside>/user/` 片段，经
+`/user` 寻址（`aside.afsd.io` Host 解析，零硬编码 DID）。`/files` 与 `aside/` wrapper 均已去除。
+
+## Usage
+
+```ts
+import { DIDSpace } from "@aigne/afs-did-space/local";
+
+const space = new DIDSpace({
+  rootPath: "~/.afs/spaces",
+  userDid: "did:abt:z1...",
+});
+
+const afs = await space.getInstanceSpace({
+  instanceDid: "did:abt:z1blocklet",
+  role: "system",
+});
+await afs.write("/hello.txt", { content: "hello" });
+```
+
+Backends:
+- `@aigne/afs-did-space/local` — `local.ts:DIDSpace`（文件系统 + SQLite）
+- `@aigne/afs-did-space/cloudflare` — `cloudflare.ts:CloudflareDIDSpace`（D1 + R2）
+- `RemoteUserSpaceAFS` — HTTP REST 客户端（**deprecated**，已被上文 afs-rpc transport 取代）
+
+## Object GC（Model B — global pool + index-layer read-auth + global sweep）
+
+内容寻址对象存在**一个全局池** `objects/{cid}`（跨用户去重）。跨用户/跨 blocklet
+的读隔离由**索引层授权**强制：`readHandler` 在返回 `.objects/{cid}` 字节前先查
+`treeIndex.isReferenced(cid)`（view-local：blocklet provider 是 prefix-local，
+space-root 是 whole-scope），未引用 → `AFSNotFoundError`（404，不泄露存在性）。
+
+两类引用检查（名字、scope、表都不同——见 design §3）：
+
+| 名字 | 问题 | scope | 表 |
+|---|---|---|---|
+| `TreeIndex.isReferenced(cid, pathPrefix?)` | "本 view 见过 cid 吗？"（**授权**） | view-local（prefix-local / whole-scope） | 三路 `entries.cid ∪ changelog.cid ∪ changelog.old_cid` |
+| `referencedAnywhere{D1,Libsql}(conn, cid)` | "还有 LIVE 文件指向 cid 吗？"（**存活**） | scope-blind | **仅 `entries.cid`**（NOT changelog，Path Y §0.2） |
+
+GC 流程：overwrite/delete 把旧 cid `enqueue` 到 `gc_queue (cid, queued_at)`；
+写入时 `gcQueue.remove(writtenCid)` 反入队（关闭去重 re-reference race）。
+`runGc()`（`run-gc.ts`，runtime-agnostic）每个候选：`assertValidCid` → **删除时刻
+fresh** 重查 `referencedAnywhere` → `objectStore.delete(objectKeyForCid(cid))`。
+单项 try/catch；crash 在 delete 与 remove 之间 → 下次幂等重试，绝不丢 live object。
+poisoned row（`cid="../_metadata.db"`）被 `assertValidCid` 挡下，永不传给 delete。
+
+Grace 默认 **7 天**（`DEFAULT_GC_GRACE_MS`），由 `runGc` 显式传给 `fetchCandidates`，
+是 behind/offline 设备的唯一保护（§0.2/§7）。
+
+触发：
+- **Node**：`arc space gc [--grace <ms>] [--limit <n>]`（一次性扫，不需 daemon）；
+  daemon 起 croner `0 * * * *`，`DIDSpace.close()` 停止它。
+- **Cloudflare**：`initHost` 注册 `ScheduledTask { id:"didspace-gc", cron:"0 * * * *" }`，
+  wrangler `[triggers] crons`（每个 env 重声明——non-inheritable）驱动 `scheduled()`。
+
+客户端契约（§4.7.2，gates GC go-live）：`SyncEngine` 对 object-read 404 分类——
+**superseded**（被同路径更晚的行取代）→ benign skip + 推进 cursor；**current**
+（manifest / 增量最新 put / 冲突 winner）→ `CurrentObjectMissingError` 硬错误 +
+cursor **pinned**（下次 sync 重访）。TS/Swift/Kotlin 三端 parity。
+
+## Collection query（`/.actions/query`）
+
+did-space 是 typed collection query 的参考引擎（afs-collection-query，2026-06）。
+三个 TreeIndex backend（sqlite / memory / d1）lockstep 实现同一语义
+（`src/tree-query.ts` 单源 SQL + JS executor；`test/tree-query-lockstep.test.ts`）。
+
+- **声明门**：仅当 backing index 实现引擎时才在 `/.meta/.capabilities` 的
+  `standardActions` 声明（declare ⇒ execute）。声明块：`doc` + `groupBy` + `annotate`。
+- **记录视图**：dir-per-record（`doc: "item.json"` join 子文档）或
+  file-per-record（无 doc，行内 content 即 record）。
+- **where 方言**：leaf `{field, eq|in|notIn|contains|gte|lte}` / `{all:[...]}` /
+  扁平等值 map。字符串大小写不敏感；数字/布尔 type-strict（SQL 侧 json_type
+  门控，布尔 groupBy 经 `'[true]'/'[false]'` json_each 源保型）；`notIn` 兜底桶
+  吃缺失/null；`contains` 要求数组字段；malformed JSON 记录折叠为 NULL record。
+- **排序/分页**：orderBy 白名单字段 + keyset cursor v2（name tiebreak）；
+  `total` 为 post-WHERE 精确计数；`count: true` 只回计数。
+- **provider 约束**：单 orderBy 键、不支持 `text`——违反抛
+  `AFSValidationError`（绝不静默降级）。
+
+## Conformance
+
+每个 backend 跑 `runProviderTests()` 全套（21 测试套件）。新 backend 必须覆盖。

package/dist/_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.cjs

@@ -0,0 +1,11 @@
+
+//#region \0@oxc-project+runtime@0.108.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+exports.__decorate = __decorate;

package/dist/_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs

@@ -0,0 +1,10 @@
+//#region \0@oxc-project+runtime@0.108.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+export { __decorate };

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,29 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+exports.__toESM = __toESM;

package/dist/afs-metadata-context.cjs

@@ -0,0 +1,20 @@
+
+//#region src/afs-metadata-context.ts
+const contextMap = /* @__PURE__ */ new WeakMap();
+/** Attach a metadata context to an AFS instance. Used by DIDSpace. */
+function attachMetadataContext(afs, ctx) {
+	contextMap.set(afs, ctx);
+}
+/** Look up the metadata context for an AFS instance. Returns undefined if none. */
+function getMetadataContext(afs) {
+	return contextMap.get(afs);
+}
+/** Detach context — exported for tests that want to simulate non-DIDSpace AFS. */
+function detachMetadataContext(afs) {
+	contextMap.delete(afs);
+}
+
+//#endregion
+exports.attachMetadataContext = attachMetadataContext;
+exports.detachMetadataContext = detachMetadataContext;
+exports.getMetadataContext = getMetadataContext;

package/dist/afs-metadata-context.d.cts

@@ -0,0 +1,21 @@
+import { MetadataDB } from "./metadata-db.cjs";
+import { AFS } from "@aigne/afs";
+
+//#region src/afs-metadata-context.d.ts
+interface AFSMetadataContext {
+  /** User-level MetadataDB (e.g. ~/.afs/spaces/{userDid}/_metadata.db) */
+  metadataDb: MetadataDB;
+  /** Root directory of the user's DID space (e.g. ~/.afs/spaces/{userDid}) */
+  userDir: string;
+  /** Scope used for entries rows — bare userDid */
+  scope: string;
+}
+/** Attach a metadata context to an AFS instance. Used by DIDSpace. */
+declare function attachMetadataContext(afs: AFS, ctx: AFSMetadataContext): void;
+/** Look up the metadata context for an AFS instance. Returns undefined if none. */
+declare function getMetadataContext(afs: AFS): AFSMetadataContext | undefined;
+/** Detach context — exported for tests that want to simulate non-DIDSpace AFS. */
+declare function detachMetadataContext(afs: AFS): void;
+//#endregion
+export { AFSMetadataContext, attachMetadataContext, detachMetadataContext, getMetadataContext };
+//# sourceMappingURL=afs-metadata-context.d.cts.map

package/dist/afs-metadata-context.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-metadata-context.d.cts","names":[],"sources":["../src/afs-metadata-context.ts"],"mappings":";;;;UAaiB,kBAAA;EAMV;EAJL,UAAA,EAAY,UAAA;EAUE;EARd,OAAA;;EAEA,KAAA;AAAA;;iBAMc,qBAAA,CAAsB,GAAA,EAAK,GAAA,EAAK,GAAA,EAAK,kBAAA;;iBAKrC,kBAAA,CAAmB,GAAA,EAAK,GAAA,GAAM,kBAAA;;iBAK9B,qBAAA,CAAsB,GAAA,EAAK,GAAA"}

package/dist/afs-metadata-context.d.mts

@@ -0,0 +1,21 @@
+import { MetadataDB } from "./metadata-db.mjs";
+import { AFS } from "@aigne/afs";
+
+//#region src/afs-metadata-context.d.ts
+interface AFSMetadataContext {
+  /** User-level MetadataDB (e.g. ~/.afs/spaces/{userDid}/_metadata.db) */
+  metadataDb: MetadataDB;
+  /** Root directory of the user's DID space (e.g. ~/.afs/spaces/{userDid}) */
+  userDir: string;
+  /** Scope used for entries rows — bare userDid */
+  scope: string;
+}
+/** Attach a metadata context to an AFS instance. Used by DIDSpace. */
+declare function attachMetadataContext(afs: AFS, ctx: AFSMetadataContext): void;
+/** Look up the metadata context for an AFS instance. Returns undefined if none. */
+declare function getMetadataContext(afs: AFS): AFSMetadataContext | undefined;
+/** Detach context — exported for tests that want to simulate non-DIDSpace AFS. */
+declare function detachMetadataContext(afs: AFS): void;
+//#endregion
+export { AFSMetadataContext, attachMetadataContext, detachMetadataContext, getMetadataContext };
+//# sourceMappingURL=afs-metadata-context.d.mts.map

package/dist/afs-metadata-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-metadata-context.d.mts","names":[],"sources":["../src/afs-metadata-context.ts"],"mappings":";;;;UAaiB,kBAAA;EAMV;EAJL,UAAA,EAAY,UAAA;EAUE;EARd,OAAA;;EAEA,KAAA;AAAA;;iBAMc,qBAAA,CAAsB,GAAA,EAAK,GAAA,EAAK,GAAA,EAAK,kBAAA;;iBAKrC,kBAAA,CAAmB,GAAA,EAAK,GAAA,GAAM,kBAAA;;iBAK9B,qBAAA,CAAsB,GAAA,EAAK,GAAA"}

package/dist/afs-metadata-context.mjs

@@ -0,0 +1,18 @@
+//#region src/afs-metadata-context.ts
+const contextMap = /* @__PURE__ */ new WeakMap();
+/** Attach a metadata context to an AFS instance. Used by DIDSpace. */
+function attachMetadataContext(afs, ctx) {
+	contextMap.set(afs, ctx);
+}
+/** Look up the metadata context for an AFS instance. Returns undefined if none. */
+function getMetadataContext(afs) {
+	return contextMap.get(afs);
+}
+/** Detach context — exported for tests that want to simulate non-DIDSpace AFS. */
+function detachMetadataContext(afs) {
+	contextMap.delete(afs);
+}
+
+//#endregion
+export { attachMetadataContext, detachMetadataContext, getMetadataContext };
+//# sourceMappingURL=afs-metadata-context.mjs.map

package/dist/afs-metadata-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-metadata-context.mjs","names":[],"sources":["../src/afs-metadata-context.ts"],"sourcesContent":["/**\n * AFS → MetadataDB context binding (Task 1.3).\n *\n * DIDSpace attaches metadata context to each AFS instance it creates so that\n * rsync.buildManifest() can default to the O(1) SQL path without explicit\n * `localMetadataDb` arguments from callers.\n *\n * Module-local WeakMap — no global singleton, no cross-test leakage.\n */\n\nimport type { AFS } from \"@aigne/afs\";\nimport type { MetadataDB } from \"./metadata-db.js\";\n\nexport interface AFSMetadataContext {\n  /** User-level MetadataDB (e.g. ~/.afs/spaces/{userDid}/_metadata.db) */\n  metadataDb: MetadataDB;\n  /** Root directory of the user's DID space (e.g. ~/.afs/spaces/{userDid}) */\n  userDir: string;\n  /** Scope used for entries rows — bare userDid */\n  scope: string;\n}\n\nconst contextMap = new WeakMap<AFS, AFSMetadataContext>();\n\n/** Attach a metadata context to an AFS instance. Used by DIDSpace. */\nexport function attachMetadataContext(afs: AFS, ctx: AFSMetadataContext): void {\n  contextMap.set(afs, ctx);\n}\n\n/** Look up the metadata context for an AFS instance. Returns undefined if none. */\nexport function getMetadataContext(afs: AFS): AFSMetadataContext | undefined {\n  return contextMap.get(afs);\n}\n\n/** Detach context — exported for tests that want to simulate non-DIDSpace AFS. */\nexport function detachMetadataContext(afs: AFS): void {\n  contextMap.delete(afs);\n}\n"],"mappings":";AAsBA,MAAM,6BAAa,IAAI,SAAkC;;AAGzD,SAAgB,sBAAsB,KAAU,KAA+B;AAC7E,YAAW,IAAI,KAAK,IAAI;;;AAI1B,SAAgB,mBAAmB,KAA0C;AAC3E,QAAO,WAAW,IAAI,IAAI;;;AAI5B,SAAgB,sBAAsB,KAAgB;AACpD,YAAW,OAAO,IAAI"}

package/dist/blocklet-hook.cjs

@@ -0,0 +1,180 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/blocklet-hook.ts
+/**
+* Blocklet publish/resolve write & delete hooks (#674 Phase 3, v2).
+*
+* AFS-native registration keyed on a PUBLISH MARKER, not `blocklet.yaml`:
+* `arc deploy` writes `<blocklet-root>/.blocklet-publish.json` LAST (always —
+* even for blocklets that have no `blocklet.yaml`, e.g. a plain `index.html`
+* one), and that write registers the blocklet in the global resolve table under
+* `resolve/blocklet/<id>`. The CF/Node serve path reads the table back to find
+* the owner space + path. There is NO REST endpoint — registration rides the
+* AFS write of the marker, mirroring how `.share` files reconcile.
+*
+* Why a marker and not `blocklet.yaml`: not every blocklet has a manifest, and
+* the blocklet's identity at publish time is the target slug
+* (`/user/blocklets/<slug>/`), which `arc deploy` already knows (manifest id
+* else dir name). Keying on a publish-written marker (a) works for ALL blocklet
+* shapes, (b) leaves the developer's files untouched (so a static blocklet stays
+* a static blocklet — a synthesized manifest could flip its serve type), and
+* (c) registers only on an explicit publish, not on any incidental manifest write.
+*
+* Contract (see planning/did-integration/blocklet-publish-resolve/design.md):
+*   marker  : <blocklet-root>/.blocklet-publish.json  = { "id": "<slug>", ... }
+*   register: resolve/blocklet/<id> → { owner, path, type:"blocklet", name:id }
+*     - owner = PLAINTEXT space-owner DID (so the reader can open the space)
+*     - path  = the blocklet root (dir holding the marker), captured at write
+*               time — scope-absolute, so resolve replays it regardless of WHERE
+*               it was written (`/user/...` lands physically under
+*               `blocklets/<instance>/user/...` and we capture that real path)
+*   resolve : resolve/blocklet/<id> → { owner, path }
+*   serve   : getUserSpace(owner) → createAfsBlockletReader(afs, path)
+*
+* All hooks are best-effort / fail-soft: a marker that doesn't parse or has no
+* `id`, or a registration failure, MUST NOT break the underlying file write.
+*
+* #764 Phase 4 extends the marker with an optional `domains: string[]` (from
+* the manifest's `sites[].domains`) that also registers `resolve/domain/<domain>`
+* → { did, owner, path }. This is the ONE deliberate exception to fail-soft: a
+* domain already owned by a different owner rejects the write loudly instead
+* of silently overwriting — see `applyBlockletWriteHook`'s doc comment.
+*/
+const log = (0, _aigne_afs.makeNsLog)("provider:did-space:blocklet-hook");
+/** The publish marker `arc deploy` writes (last) into a blocklet's DID-Space root. */
+const BLOCKLET_PUBLISH_MARKER = ".blocklet-publish.json";
+/**
+* True if `afsPath`'s basename is the publish marker. Accepts a leading slash
+* and any directory depth.
+*/
+function isBlockletPublishMarkerPath(afsPath) {
+	const p = afsPath.startsWith("/") ? afsPath.slice(1) : afsPath;
+	return p === BLOCKLET_PUBLISH_MARKER || p.endsWith(`/${BLOCKLET_PUBLISH_MARKER}`);
+}
+/**
+* Parse a publish-marker payload and extract `{id, did, domains}`. Returns
+* null on any failure (non-UTF-8, non-JSON, not an object, missing/blank
+* `id`) — the caller treats null as "not registerable" and leaves the write
+* untouched. A malformed `domains` field (not an array, or with non-string /
+* empty elements) is NOT a parse failure — it is silently dropped down to
+* only the valid string entries (empty result → field omitted), same
+* fail-soft spirit as the rest of this parser.
+*/
+function parseBlockletPublishMarker(bytes) {
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return null;
+	}
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+	const record = doc;
+	const id = record.id;
+	if (typeof id !== "string" || id.length === 0) return null;
+	const did = typeof record.did === "string" && record.did.length > 0 ? record.did : void 0;
+	const domains = Array.isArray(record.domains) ? record.domains.filter((d) => typeof d === "string" && d.length > 0) : void 0;
+	const publishVersion = typeof record.publishVersion === "number" && Number.isFinite(record.publishVersion) ? record.publishVersion : void 0;
+	const hasWebCache = typeof record.hasWebCache === "boolean" ? record.hasWebCache : void 0;
+	return {
+		id,
+		did,
+		...domains && domains.length > 0 ? { domains } : {},
+		...publishVersion !== void 0 ? { publishVersion } : {},
+		...hasWebCache !== void 0 ? { hasWebCache } : {}
+	};
+}
+/** Blocklet root for a marker tree path: strip the trailing marker segment. */
+function blockletDir(treePath) {
+	const norm = treePath.replace(/^\/+/, "");
+	const idx = norm.lastIndexOf("/");
+	return idx === -1 ? "" : norm.slice(0, idx);
+}
+/**
+* applyBlockletWriteHook — called AFTER a successful publish-marker write in any
+* DID Space write path. Registers `resolve/blocklet/<id>` → {owner, path} and,
+* when the marker declares `domains` (#764), `resolve/domain/<domain>` →
+* {did, owner, path} for each.
+*
+* No-op when the resolver is absent, the path isn't the publish marker, or the
+* marker has no usable `id`.
+*
+* Domain conflict is a DELIBERATE, SCOPED exception to this file's usual
+* fail-soft rule: the user wants a domain claimed by a different owner to
+* reject the publish loudly, not silently succeed into someone else's slot.
+* The conflict check therefore runs OUTSIDE the fail-soft try/catch below —
+* validate every domain BEFORE registering anything (so a conflict on one
+* domain never leaves a partial registration), then register. A registration
+* failure unrelated to a conflict (e.g. a transient resolver error) keeps the
+* existing fail-soft contract: the marker write itself must not fail.
+*/
+async function applyBlockletWriteHook(params) {
+	if (!params.resolver || !isBlockletPublishMarkerPath(params.afsPath)) return;
+	const marker = parseBlockletPublishMarker(params.bytes);
+	if (!marker) return;
+	const { id, domains = [] } = marker;
+	const did = marker.did ?? `did:blocklet:${id}`;
+	const path = blockletDir(params.treePath);
+	const { resolver, ownerDid } = params;
+	const existingBlocklet = await resolver.resolveBlocklet(id);
+	if (existingBlocklet && existingBlocklet.owner !== ownerDid) throw new _aigne_afs.AFSAlreadyExistsError(id, `blocklet "${id}" is already registered to a different owner`);
+	for (const domain of domains) {
+		const existing = await resolver.resolveDomain(domain);
+		if (existing && existing.owner !== ownerDid) throw new _aigne_afs.AFSAlreadyExistsError(domain, `domain "${domain}" is already registered to a different owner`);
+	}
+	const { publishVersion, hasWebCache } = marker;
+	try {
+		await resolver.registerBlocklet(id, {
+			owner: ownerDid,
+			path,
+			type: "blocklet",
+			name: id,
+			...publishVersion !== void 0 ? { publishVersion } : {},
+			...hasWebCache !== void 0 ? { hasWebCache } : {}
+		});
+		for (const domain of domains) await resolver.registerDomain(domain, {
+			did,
+			owner: ownerDid,
+			path,
+			...publishVersion !== void 0 ? { publishVersion } : {},
+			...hasWebCache !== void 0 ? { hasWebCache } : {}
+		});
+		const stale = (await resolver.domainsForBlocklet(ownerDid, path)).filter((d) => !domains.includes(d));
+		for (const domain of stale) await resolver.unregisterDomain(domain);
+		if (params.purgeCachesForDomains && domains.length > 0) await params.purgeCachesForDomains(domains);
+	} catch (err) {
+		log.warn(`[blocklet-hook] registration for "${id}" failed: ${err instanceof Error ? err.message : err}`);
+	}
+}
+/**
+* applyBlockletDeleteHook — called AFTER a publish marker is deleted. Looks up
+* the registered blocklet by (owner, path) and unregisters it, along with any
+* domains registered for the same (owner, path) (#764). We key by path rather
+* than re-parsing the marker because the delete path has no bytes; the
+* (owner, path) pair uniquely identifies a published blocklet (one marker per
+* root). No-op when nothing matches.
+*/
+async function applyBlockletDeleteHook(params) {
+	if (!params.resolver || !isBlockletPublishMarkerPath(params.afsPath)) return;
+	const path = blockletDir(params.treePath);
+	const { resolver, ownerDid } = params;
+	try {
+		const all = await resolver.listBlocklets();
+		for (const { id, entry } of all) if (entry.owner === ownerDid && entry.path === path) await resolver.unregisterBlocklet(id);
+		const domains = await resolver.domainsForBlocklet(ownerDid, path);
+		for (const domain of domains) await resolver.unregisterDomain(domain);
+	} catch (err) {
+		log.warn(`[blocklet-hook] unregister for path "${path}" failed: ${err instanceof Error ? err.message : err}`);
+	}
+}
+
+//#endregion
+exports.BLOCKLET_PUBLISH_MARKER = BLOCKLET_PUBLISH_MARKER;
+exports.applyBlockletDeleteHook = applyBlockletDeleteHook;
+exports.applyBlockletWriteHook = applyBlockletWriteHook;

package/dist/blocklet-hook.d.cts

@@ -0,0 +1,29 @@
+//#region src/blocklet-hook.d.ts
+/** The publish marker `arc deploy` writes (last) into a blocklet's DID-Space root. */
+declare const BLOCKLET_PUBLISH_MARKER = ".blocklet-publish.json";
+/** Shape of the publish marker payload. */
+interface BlockletPublishMarker {
+  /** The blocklet slug — manifest `id` else the publish dir name. Resolve key. */
+  id: string;
+  /** Full blocklet DID. Load-bearing for domain registration (#764) — see below. */
+  did?: string;
+  /** ISO publish timestamp (informational). */
+  publishedAt?: string;
+  /** Custom domains declared under `sites[].domains` in the manifest (#764). */
+  domains?: string[];
+  /**
+   * Monotonic timestamp (Date.now()) written by the CLI at publish time.
+   * Materialized into resolve entries; used by CF Worker edge-cache invalidation
+   * so that the cached page key changes on every publish (#1110).
+   */
+  publishVersion?: number;
+  /**
+   * True when the published bundle includes pre-rendered `.web-cache/` content.
+   * Materialized into resolve entries so the CF Worker knows to do edge-caching
+   * without checking the blocklet files (#1110).
+   */
+  hasWebCache?: boolean;
+}
+//#endregion
+export { BLOCKLET_PUBLISH_MARKER, BlockletPublishMarker };
+//# sourceMappingURL=blocklet-hook.d.cts.map

package/dist/blocklet-hook.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocklet-hook.d.cts","names":[],"sources":["../src/blocklet-hook.ts"],"mappings":";;cA8Ca,uBAAA;;UAGI,qBAAA;;EAEf,EAAA;;EAEA,GAAA;;EAEA,WAAA;;EAEA,OAAA;;;;;;EAMA,cAAA;;;;;;EAMA,WAAA;AAAA"}

package/dist/blocklet-hook.d.mts

@@ -0,0 +1,29 @@
+//#region src/blocklet-hook.d.ts
+/** The publish marker `arc deploy` writes (last) into a blocklet's DID-Space root. */
+declare const BLOCKLET_PUBLISH_MARKER = ".blocklet-publish.json";
+/** Shape of the publish marker payload. */
+interface BlockletPublishMarker {
+  /** The blocklet slug — manifest `id` else the publish dir name. Resolve key. */
+  id: string;
+  /** Full blocklet DID. Load-bearing for domain registration (#764) — see below. */
+  did?: string;
+  /** ISO publish timestamp (informational). */
+  publishedAt?: string;
+  /** Custom domains declared under `sites[].domains` in the manifest (#764). */
+  domains?: string[];
+  /**
+   * Monotonic timestamp (Date.now()) written by the CLI at publish time.
+   * Materialized into resolve entries; used by CF Worker edge-cache invalidation
+   * so that the cached page key changes on every publish (#1110).
+   */
+  publishVersion?: number;
+  /**
+   * True when the published bundle includes pre-rendered `.web-cache/` content.
+   * Materialized into resolve entries so the CF Worker knows to do edge-caching
+   * without checking the blocklet files (#1110).
+   */
+  hasWebCache?: boolean;
+}
+//#endregion
+export { BLOCKLET_PUBLISH_MARKER, BlockletPublishMarker };
+//# sourceMappingURL=blocklet-hook.d.mts.map

package/dist/blocklet-hook.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocklet-hook.d.mts","names":[],"sources":["../src/blocklet-hook.ts"],"mappings":";;cA8Ca,uBAAA;;UAGI,qBAAA;;EAEf,EAAA;;EAEA,GAAA;;EAEA,WAAA;;EAEA,OAAA;;;;;;EAMA,cAAA;;;;;;EAMA,WAAA;AAAA"}