halfcode-compiler.xnl 0.2.1 → 0.2.3

package/dist/system-skills/resource-dsl/language.md

@@ -0,0 +1,64 @@
+# Language Axioms
+
+## 身份与分类
+
+- 根 tag 是资源 kind；PascalCase 保留给 DSL 结构节点。
+- 可跨容器复用的资源在 `#id` 使用点分 FQN，例如 `#demo.resource_workflow.prepare_data`。
+- 文件路径只负责物理布局，不决定 kind 或 identity。移动文件不改变 `#id`。
+- `apiVersion` 与 `version` 写在 metadata 位；title、lifecycle、description 等业务数据若属于该 Kind，则写入 `{}`。
+- 通用资源边界只要求根 `#id` 与 `apiVersion`。`lifecycle`、`description` 的存在性和语义由具体 Kind 或 consumer contract 决定，resource-core 不提供虚假默认值。
+- 每个 KindDefinition 显式声明 `currentApiVersion` 与 `supportedApiVersions`；loader 不猜测未知版本，也不自动执行迁移。具体系统通过公开 `ResourceMigrationRegistry` 注册纯转换函数，得到唯一版本链后再加载目标文档。
+- XNL authority 默认单根。只有 source shape 严格为 `single-file` 的 Kind 可以通过 `documentCardinality = "many"` 授权同 Kind forest；每个顶层根仍是独立资源，`[]` 继续只表达节点内部的重复子项。
+- 静态描述数据由所属节点自持，不寄存在另一域再引用回来。
+
+## 子域与重复事实
+
+`()` 表示父节点拥有的唯一子域概念。同一父节点的 `()` 中，同名 tag 只能出现一次。重复条目由复数子域的 `[]` 承载：
+
+```xnl
+<ResourcePackage #demo.package (
+  <Catalogs [
+    <Catalog #functions { kind = "Function" root = "vfs://./Functions/" entry = "manifest.xnl" }>
+    <Catalog #skills { kind = "SkillCapsule" root = "vfs://./Skills/" entry = "manifest.xnl" }>
+  ]>
+)>
+```
+
+直接、有序或可重复的事实进入 `[]`。禁止为了凑层级增加没有领域语义的 `Nodes`、`Items` 或 `Block` 包装；复数容器必须确实代表一个唯一子域概念。
+
+## URI 与代码引用
+
+所有跨节点/文件引用都是引号字符串 URI：
+
+| 目标 | canonical 形态 | 示例 |
+|---|---|---|
+| 当前 bundle 相对文件 | `vfs://./<path>` | `vfs://./instruction.md` |
+| workspace 文件 | `vfs://@/<path>` | `vfs://@/apps/demo/src/procedures.ts` |
+| TypeScript 导出 | `vfs://...#<ExportName>` | `vfs://@/apps/demo/src/procedures.ts#prepareProcedure` |
+| 规范资源 identity | `resource://<FQN>` | `resource://demo.resource_workflow.prepare_data` |
+| 当前容器 id | `<domain>://#<id>` | `catalog://#functions` |
+
+代码引用必须包含 export fragment。XNL 只保存声明式 binding；函数、闭包、表达式字符串和 handler object 不得内嵌到 XNL。执行代码的协议和副作用由 runtime/component contract 定义，不属于 parser。
+
+## Authoring 与 projection
+
+```text
+XNL authority document
+  -> xnl-core node tree
+  -> validated normalized resource descriptor + provenance
+  -> registry / mapping / application assembly projections
+```
+
+- authority：磁盘上的 `.xnl` 文档；唯一可编辑事实。
+- parser tree：语法投影，只由 resource-core loader 消费。
+- normalized descriptor：稳定领域边界，携带 `resourceId`、`kind`、metadata、members、subdomains、`documentUri`、`logicalPath`；Kind-owned 可选属性保持存在或缺失的原始事实。
+- consumer projection：可重建；不得暴露 parser node 内部字段，也不得反写 authority。
+
+package provenance 从 package manifest、document URI 与 logical path 派生。descriptor 不重复保存一份可由路径计算的 package identity。
+
+## 声明式限制
+
+- 一个 bundle 内的配置只使用 XNL，不引入 JSON/XML/YAML 第二配置入口。
+- 动态代码保存在 `.ts` 等外部文件，通过 `vfs://...#Export` 挂接。
+- 不允许将 XML attributes 转换成 `@_name` 或其他前缀键后暴露给 consumer。
+- 不允许根据文件名猜测 kind；文件内容的 tag 才是 authority。

package/dist/system-skills/resource-dsl/manifest.xnl

@@ -0,0 +1,10 @@
+<ResourcePackage #Halfcode.ResourceDsl.Package apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Canonical Halfcode Resource DSL documentation and consumer Skill resources."
+} (
+  <Catalogs [
+    <Catalog #KindDefinitions { kind = "KindDefinition" shape = "directory" root = "vfs://./KindDefinitions/" entry = "manifest.xnl" }>
+    <Catalog #WikiPages { kind = "WikiPage" shape = "directory" root = "vfs://./WikiPages/" entry = "manifest.xnl" }>
+    <Catalog #SkillCapsules { kind = "SkillCapsule" shape = "directory" root = "vfs://./SkillCapsules/" entry = "manifest.xnl" }>
+  ]>
+)>

package/dist/system-skills/resource-dsl/migration.md

@@ -0,0 +1,40 @@
+# XML To XNL Migration
+
+## 迁移原则
+
+迁移单位是“资源语义”，不是 tag/attribute 的逐字符替换：
+
+| XML-era 表达 | XNL authority |
+|---|---|
+| 根 element 名 | 根 tag（resource kind） |
+| `Id`/`Name` 等身份 attribute | 根 `#id` FQN；display name 若存在则留在 `{}` |
+| `Version`/schema version | metadata 位的 `version`/`apiVersion` |
+| 普通 attributes | `{}` 中归节点所有的属性 |
+| 唯一 child section | `()` 中的唯一子域 |
+| 重复 child elements | 父 `[]` 或复数子域的 `[]` |
+| 文件路径/code export | 引号字符串 `vfs://...#Export` |
+| parser `@_foo`/XmlObject | 不迁移；在 normalized descriptor 边界消失 |
+
+## 顺序
+
+1. 用 `KindDefinition` 明确 kind contract。
+   - 声明 `currentApiVersion` 与 `supportedApiVersions`。
+   - 对不可直接兼容的历史版本，在代码侧 `ResourceMigrationRegistry` 注册唯一纯转换链；XNL 不内嵌 transformer。
+2. 将 package/catalog authority 改为 XNL。
+3. 逐个资源按领域语义分配 `{}`、`()`、`[]`，保留稳定 `#id`。
+4. 将路径与代码引用规范为 VFS URI。
+5. 通过 resource-core 得到 normalized descriptor，再迁移 consumer。
+6. 删除兼容 XML 与 `fast-xml-parser`，以产品 XML inventory 清零作为关闭条件。
+
+## 明确拒绝
+
+- 在 TypeScript 中保留 `XmlObject`、`@_` 属性前缀或 XML child-array 作为公开类型。
+- 同一资源同时维护 XML 与 XNL 两份长期 authority。
+- 根据目录名/文件名猜 kind 或 identity。
+- 在 XNL 内嵌函数、闭包或可执行表达式字符串。
+- 用无语义的 wrapper 模拟 XML 层级。
+- 在 BusinessObject/PageObject API 尚未稳定时提前设计二者的专用 XNL schema。
+
+## 暂时兼容
+
+后续实现 track 可以在内部短期 dual-read，用于小步迁移和 characterization test；兼容层不得进入 public API，并必须在 `close-xnl-only-product-surface` track 删除。

package/dist/system-skills/resource-dsl/projections.md

@@ -0,0 +1,142 @@
+# Resource Projections and Dependency Authority
+
+## Authority map
+
+资源 authoring、组合与运行闭包是三个不同层次，不能互相替代：
+
+| Fact | Authority owner | Halfcode projection |
+|---|---|---|
+| package、Catalog、KindDefinition、resource descriptor | XNL ResourcePackage | `LoadedResourceTree extends ResourceTree` |
+| layer precedence | 调用方提供的有序 `ResourceLayerInput[]` | `EffectiveResourceRegistry.layers` |
+| suppression | 调用方显式提供的 `ResourceTombstone` | effective/tombstone/shadow provenance |
+| Kind-specific dependency semantics | 对应 Kind owner 或 consumer | `ResourceDependencyEdge[]` |
+| XNL authority bytes | canonical loader 的同一次 raw-byte read | `LoadedResourceTree.contentIdentities` |
+| Kind-specific material bytes | Kind owner 提供的显式 digest contribution | effective `ResourceContentIdentity` |
+| roots 与 dependency closure | 调用方的显式 roots 加 typed edges | `ResourceDependencySnapshot` |
+
+`ResourceTree` 是单个已验证 package 的规范化结果。`EffectiveResourceRegistry` 只是多个 tree 的确定性只读投影；它会 deep-clone/freeze record、metadata、node/value 与 KindDefinition facts，避免调用方之后修改输入而改变既有投影，但不会原地冻结或改写旧 `ResourceTree`。`ResourceDependencySnapshot` 又是某组 roots 在一个 content-sensitive registry revision 上的冻结闭包。两种投影都可由 authority facts 重建，不得反写任一 XNL package，也不得成为第二份 authoring 真源。
+
+Snapshot builder 只接受同一 resource-core runtime 中由 `composeLayeredResourceRegistry()` 返回的 canonical immutable registry。手工构造、浅拷贝或改写 revision 字段的结构相似对象会 fail closed；需要跨进程恢复时，应从 XNL packages、ordered layers 与 tombstones 重新组合。Snapshot 会复制并冻结自己的 origin facts，不共享可变调用方引用。
+
+## Ordered named layers
+
+layer 只包含一个不透明、稳定的 `id` 和一个已验证 `ResourceTree`。数组从低 precedence 到高 precedence 排列，后一个 layer 优先。Halfcode 不保留特殊 layer 名称，不根据名称重排，也不拥有任何产品安装目录或机器路径策略；实际 roots 由 consumer 在调用 resource-core 之前绑定。
+
+组合规则是：
+
+1. 同一 `resourceId`、同一 kind 的高层资源成为 effective；低层 origin 留在 `shadowed`。
+2. 同一 identity 跨 kind，或同一 resource kind 的规范化 KindDefinition contract 不兼容，组合失败并返回稳定 diagnostics。
+3. 高层没有某个资源只表示“未提供”，绝不表示删除。
+4. 删除语义必须通过 `ResourceTombstone { resourceId, expectedKind?, reason? }` 显式声明；tombstone origin 与历史保留在 projection 中。
+5. `byKind` 只包含 effective resources；完整 effective、shadow 与 tombstone 证据由 `byId` 保存。
+6. `documentUri` 必须是与安全相对 `logicalPath` 一致的 canonical `vfs://@/` URI；非 loader 来源的绝对机器路径或 traversal provenance 会 fail closed。
+
+```ts
+import {
+  composeLayeredResourceRegistry,
+  type ResourceLayerInput,
+} from "halfcode-compiler.xnl/resource-core"
+
+declare const lowerPackage: ResourceLayerInput["tree"]
+declare const higherPackage: ResourceLayerInput["tree"]
+
+const registry = composeLayeredResourceRegistry({
+  layers: [
+    { id: "base", tree: lowerPackage },
+    {
+      id: "override",
+      tree: higherPackage,
+      tombstones: [{ resourceId: "demo.retired", expectedKind: "Function" }],
+    },
+  ],
+})
+```
+
+示例中的名字仅用于展示调用顺序，不携带预定义语义。consumer 可以选择任何稳定 id；改变数组顺序才会改变 precedence。
+
+## Explicit content identity
+
+canonical loader 对每个 XNL authority 文件只读取一次 raw bytes：同一次读取同时用于 fatal UTF-8 decode、XNL parse 和 SHA-256。成功加载后返回 additive `LoadedResourceTree`；其 `contentIdentities` 精确覆盖 `registry.byKind` 的业务 resources，不包含 package manifest 或 KindDefinition。multi-root document 的 roots 共享同一文件级 `authorityDigest`，但各自的 `resourceId` 和 `contentDigest` 独立。
+
+`ResourceTree` 仍是兼容父接口，手工 structural tree 仍可参与 generic layer composition。只有 canonical loader 返回并由当前 runtime 登记的 `LoadedResourceTree` 才能进入 `resolveEffectiveResourceContentIdentities()`。projector exact 核对 registry 的 layer id、顺序、package 与 effective origin，从每个 effective layer 选择 loader identity；shadowed non-effective resource 与 tombstone 不进入结果。Kind owner 再把 prompt、schema、instruction 等 material 作为带稳定 `key`、`digest` 和可选 `sourceUri` 的 contribution 显式提供。
+
+`createResourceContentIdentity()` 按 UTF-16 code-unit key 顺序 canonicalize contributions，并拒绝任何重复 key；即使 digest 相同，重复或不同 provenance 也不是可静默折叠的合法事实。snapshot builder 会对全部 effective resources 重新规范化 authority/contribution facts、重算 `contentDigest` 并核对 claim；它不会只验证 roots 可达的 identity，也不会信任调用方构造的对象。`sourceUri` 是 provenance，不允许机器绝对路径进入 content revision；调用方应使用 Resource DSL 定义的逻辑 URI。
+
+```ts
+import {
+  composeLayeredResourceRegistry,
+  loadResourceTree,
+  resolveEffectiveResourceContentIdentities,
+} from "halfcode-compiler.xnl/resource-core"
+
+declare const lowerPackageRoot: string
+declare const higherPackageRoot: string
+declare const contributions: Parameters<typeof resolveEffectiveResourceContentIdentities>[0]["contributions"]
+
+const lowerPackage = await loadResourceTree({ rootDir: lowerPackageRoot })
+const higherPackage = await loadResourceTree({ rootDir: higherPackageRoot })
+const registry = composeLayeredResourceRegistry({
+  layers: [
+    { id: "lower", tree: lowerPackage },
+    { id: "higher", tree: higherPackage },
+  ],
+})
+
+const identities = resolveEffectiveResourceContentIdentities({
+  registry,
+  layers: [
+    { id: "lower", tree: lowerPackage },
+    { id: "higher", tree: higherPackage },
+  ],
+  contributions,
+})
+```
+
+示例中的 `lowerPackageRoot`、`higherPackageRoot` 与 `contributions` 由 consumer 在调用边界绑定。Halfcode 不定义机器安装目录或 layer precedence policy，也不会重复读取 XNL authority。projector 的结果可直接传给 snapshot builder；snapshot builder 仍不执行隐藏 IO。
+
+## Typed dependency closure
+
+依赖的字段语义属于 Kind owner。它负责把自己的 descriptor contract 转成 `ResourceDependencyEdge { fromResourceId, toResourceId, relation, declaredBy }`。resource-core 只校验 endpoint、从显式 roots 沿这些边遍历、拒绝可达 cycle，并生成稳定排序的 snapshot。
+
+```ts
+import {
+  buildResourceDependencySnapshot,
+  type EffectiveResourceRegistry,
+  type ResourceDependencyEdge,
+  type ResourceContentIdentity,
+} from "halfcode-compiler.xnl/resource-core"
+
+declare const registry: EffectiveResourceRegistry
+declare const workflowIdentity: ResourceContentIdentity
+declare const schemaIdentity: ResourceContentIdentity
+
+const edges: readonly ResourceDependencyEdge[] = [{
+  fromResourceId: workflowIdentity.resourceId,
+  toResourceId: schemaIdentity.resourceId,
+  relation: "uses-schema",
+  declaredBy: "WorkflowKindDefinition",
+}]
+
+const snapshot = buildResourceDependencySnapshot({
+  registry,
+  roots: [workflowIdentity.resourceId],
+  edges,
+  contentIdentities: new Map([
+    [workflowIdentity.resourceId, workflowIdentity],
+    [schemaIdentity.resourceId, schemaIdentity],
+  ]),
+})
+```
+
+普通文本、instruction 或 `ResourceNode` property 即使看起来像资源 URI，只要 Kind owner 没有提供 typed edge，就不会进入 closure。resource-core 不遍历任意字符串、不匹配自然语言关键词，也不猜测引用字段。
+
+## Deterministic revisions
+
+- content revision 覆盖 resource identity、authority digest 与按 key 排序的 material digests。
+- `compositionRevision` 覆盖显式 layer 顺序、effective identity/presence、shadow/tombstone facts、选定 KindDefinition 的 authority `resourceId`/兼容 contract 与 canonical `documentUri/logicalPath` provenance；`EffectiveResourceRegistry.revision` 是它的精确兼容别名。ResourceRecord descriptor/node/metadata bytes 不进入该摘要，而由显式 content identity 负责。不同 definition identity 不会自行把相同 normalized Kind contract 变成冲突。
+- snapshot 的 `registryRevision` 覆盖 `compositionRevision` 与全部 effective resource 的已验证 content revisions，包括当前 roots 不可达的资源。
+- `snapshotRevision` 覆盖显式 root 顺序、可达资源 content revisions、参与闭包的 typed edges 与 `registryRevision`。
+- revisions 使用带算法前缀的 SHA-256 形式；逻辑 provenance 在 projection 中保留，机器绝对路径不得进入摘要。
+- canonical object key、resource、kind、edge 与 contribution 排序固定使用 ECMAScript UTF-16 code-unit 顺序，不依赖 locale、ICU、文件枚举或 Map 插入顺序。
+
+缺失 endpoint、缺失 content identity、identity-kind/KindDefinition conflict、矛盾 digest 或 dependency cycle 都会 fail closed；调用方不会收到看似完整的 partial snapshot。

package/dist/system-skills/resource-dsl/skill-capsules.md

@@ -0,0 +1,94 @@
+# SkillCapsule Dependencies And Distribution
+
+## Identity authority
+
+新的 `SkillCapsule` descriptor 由 XNL 根节点独占 FQN、consumer-facing `name`、`apiVersion` 与 `version`。`SKILL.metadata.yaml` 只保存 title/description 等呈现字段，不重复 name/version；assembly 会把 canonical XNL name/version 投影给模板。若 descriptor 已声明 `name` 而 YAML 仍重复该字段，assembly 在 compiler 写入前以 `SKILL_CAPSULE_NAME_DUPLICATE` 失败。历史 descriptor 未声明 XNL name 时，既有 YAML name 与 FQN 尾段 fallback 继续兼容；新资源不得采用该兼容路径。
+
+XNL `version` 也是 capsule identity 与 dependency binding 的唯一 version authority。历史 YAML 若仍带 `version`，必须与 XNL 严格相等，否则 assembly 以 `SKILL_CAPSULE_VERSION_CONFLICT` 失败。
+
+```xnl
+<SkillCapsule #example.resource_lifecycle.skill.authoring
+  apiVersion="halfcode.resources/v1"
+  version="1.0.0" {
+  name = "example-resource-authoring"
+  description = "Generic resource authoring operations."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+)>
+```
+
+对应 YAML 只保存呈现字段：
+
+```yaml
+title: Example Resource Authoring
+description: Generic resource authoring operations.
+```
+
+## `SkillDependencies` 与 `Includes`
+
+两种关系不可互换，也不做名称或文本推断：
+
+- `SkillDependencies/SkillDependency` 声明同一个 `ApplicationAssembly.byFqn` resource universe 中的 sibling `SkillCapsule`。`ref` 必须是 `resource://<FQN>`，目标 kind 必须是 `SkillCapsule`，`version` 是必填的精确 binding；当前版本不解释 semver range。
+- `Includes/Include` 选择要编入当前 capsule 的 Function、PromptFragment 等普通资源。即便一个 Include 写了 `kind = "SkillCapsule"`，planner 也不会把它提升为 sibling dependency。
+
+```xnl
+<SkillDependencies [
+  <SkillDependency {
+    ref = "resource://example.resource_lifecycle.skill.resource_dsl"
+    version = "1.0.0"
+  }>
+]>
+<Includes [
+  <Include {
+    kind = "PromptFragment"
+    ref = "resource://example.resource_lifecycle.prompt.authoring_prelude"
+  }>
+]>
+```
+
+缺失目标、错误 kind、重复 dependency、精确版本不匹配和 cycle 都会 fail closed。依赖解析只读取既有 application assembly，不创建第二份 catalog 或 scanner。
+
+## 四 Skill canonical topology
+
+规范示例使用与具体产品无关的四个 Skill：
+
+```text
+resource DSL -> authoring -> devops/root
+                         run -> devops/root
+```
+
+- `devops/root` 显式依赖 `authoring` 与 `run`；
+- `authoring` 显式依赖共享 `resource DSL`；
+- `run` 与 `resource DSL` 没有 sibling dependency。
+
+完整 descriptor 分别位于 [skill-capsule-devops.xnl](examples/skill-capsule-devops.xnl)、[skill-capsule-authoring.xnl](examples/skill-capsule-authoring.xnl)、[skill-capsule-run.xnl](examples/skill-capsule-run.xnl) 和 [skill-capsule-resource-dsl.xnl](examples/skill-capsule-resource-dsl.xnl)。可加载、可规划的 bundle fixture 位于 `apps/demo-resource-workflow-authoring/resources-xnl/SkillCapsules/Topology*`。所有 consumer name 与 version 都由 XNL 声明，dependency 绑定 `1.0.0`，YAML 不重复 identity 字段。
+
+## Deterministic plan 与 atomic apply
+
+`planSkillCapsuleDistribution` 与 `applySkillCapsuleDistributionPlan` 是两个独立阶段：
+
+1. planner 从显式 roots 解析传递闭包，按固定 code-unit 顺序生成 dependency-first topology；
+2. planner 读取所有 generated/mapped bytes，并将 canonical bytes 保存为不可变、可序列化的 `contentBase64` authority；兼容字段 `content` 每次读取只返回新的 defensive copy；
+3. planner 对所有会进入 SKILL/reference/callable bytes 的资源集合按 FQN 使用固定 UTF-16 code-unit comparator 排序，并对完整 closure 做重复 output name、相同 target 与文件/目录 prefix collision preflight；
+4. plan 保存 versioned content/capsule/closure digest，且不含绝对路径、时间戳或函数对象；plan 成功或失败都不写目标 root；
+5. applier 先 fail-closed 校验非空 roots、root 可达的完整闭包、canonical base64 与全部 digest，再在 caller 提供的 `outputRoot` 同父目录 stage、readback，以 backup/rename/rollback 成组切换。
+
+每个 planned capsule 还必须包含固定路径 `references/.halfcode/provenance.json`。该文件由 compiler 生成，不由模板维护；它记录 `halfcode.skill-provenance/v1` format、`halfcode.skill-distribution/v1` generator、SkillCapsule XNL 的 FQN/apiVersion/version，以及除自身以外全部 payload files 的 canonical path/content digest。manifest 自身作为普通 planned file 进入 capsule/closure digest，因此不需要自引用摘要。applier 会在任何目标写入前从 plan 重建并 exact 校验这些 facts。
+
+```ts
+const plan = await planSkillCapsuleDistribution({
+  assembly,
+  rootSkillFqns: ["example.resource_lifecycle.skill.devops"],
+})
+
+await applySkillCapsuleDistributionPlan(plan, { outputRoot })
+```
+
+Halfcode 只拥有通用 resource dependency、plan 与 atomic apply contract；目标 root、安装位置、生命周期阶段和升级策略都由 caller/host 决定。compiler 不推导这些 policy，也不把它们写进资源 authority。
+
+## Consumer Resource DSL Skill
+
+`docs/resource-dsl/manifest.xnl` 将本目录的 canonical 文档登记为 ResourcePackage/WikiPage resources，并声明 `Halfcode.ResourceDsl.Skill.System`。compiler 从这些原始文档生成 `sys-halfcode-resource-dsl@1.0.0` 的 references；`SKILL.md` 只提供渐进加载顺序，不复制规范正文，也不包含仓库维护命令或 host 安装操作。仓库维护者继续使用 `skills/framework-resource-dsl`，两者职责不可互换。
+
+既有 `compileSkillCapsule`、`compileResourceSkillCapsule` 与 `SkillCapsulePlan` 保持兼容。新 planner/applier 和类型从 package root 及 `halfcode-compiler.xnl/skill-capsule` additive 导出。