halfcode-compiler.xnl 0.2.2 → 0.2.4

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 导出。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcode-compiler.xnl",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Compile XNL-described applications into runtime-ready skill capsules.",
   "type": "module",
   "private": false,