halfcode-compiler.xnl 0.2.8 → 0.3.0

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

@@ -1,11 +1,23 @@
-<KindDefinition #Halfcode.ResourceDsl.KindDefinition.SkillCapsule apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #Halfcode.ResourceDsl.KindDefinition.SkillCapsule envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Kind definition for the versioned Resource DSL consumer SkillCapsule."
   resourceKind = "SkillCapsule"
+  subjectFqn = "Halfcode.ResourceKind.SkillCapsule"
   sourceShapes = ["directory"]
-  currentApiVersion = "halfcode.resources/v1"
-  supportedApiVersions = ["halfcode.resources/v1"]
 } (
+  <SpecRevisions [
+    <SpecRevision #v1 {
+      specVersion = 1
+      schemaRef = "vfs://./spec-v1.schema.json"
+      schemaFingerprint = "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+      contractFingerprint = "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+      semanticValidatorFingerprint = "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+      referenceProjectionFingerprint = "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+      compilerInputFingerprint = "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      stability = "stable"
+    }>
+  ]>
+
   <DescriptorContract (
     <RequiredFiles [
       <File { name = "SKILL.metadata.yaml" }>

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

@@ -1,10 +1,22 @@
-<KindDefinition #Halfcode.ResourceDsl.KindDefinition.WikiPage apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #Halfcode.ResourceDsl.KindDefinition.WikiPage envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Kind definition for canonical documentation pages referenced from the Resource DSL package root."
   resourceKind = "WikiPage"
+  subjectFqn = "Halfcode.ResourceKind.WikiPage"
   sourceShapes = ["directory"]
-  currentApiVersion = "halfcode.resources/v1"
-  supportedApiVersions = ["halfcode.resources/v1"]
 } (
+  <SpecRevisions [
+    <SpecRevision #v1 {
+      specVersion = 1
+      schemaRef = "vfs://./spec-v1.schema.json"
+      schemaFingerprint = "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+      contractFingerprint = "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+      semanticValidatorFingerprint = "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+      referenceProjectionFingerprint = "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+      compilerInputFingerprint = "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      stability = "stable"
+    }>
+  ]>
+
   <DescriptorContract>
 )>

package/dist/system-skills/resource-dsl/SkillCapsules/System/SKILL.metadata.yaml

@@ -1,2 +1,3 @@
 title: Halfcode Resource DSL
+version: 1.0.0
 description: Author and review XNL ResourcePackages, catalogs, KindDefinitions, VFS materials, projections and SkillCapsules using the canonical Halfcode Resource DSL.

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

@@ -1,4 +1,4 @@
-<SkillCapsule #Halfcode.ResourceDsl.Skill.System apiVersion="halfcode.resources/v1" version="1.0.0" {
+<SkillCapsule #Halfcode.ResourceDsl.Skill.System envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   name = "sys-halfcode-resource-dsl"
   lifecycle = "Stable"
   description = "Author and review XNL ResourcePackages, catalogs, KindDefinitions, VFS materials, projections and SkillCapsules using the canonical Halfcode Resource DSL."

package/dist/system-skills/resource-dsl/SkillCapsules/System/resource-mappings.xnl

@@ -1,4 +1,4 @@
-<ResourceMappings #Halfcode.ResourceDsl.ResourceMappings.System apiVersion="halfcode.resources/v1" version="1.0.0" (
+<ResourceMappings #Halfcode.ResourceDsl.ResourceMappings.System envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 (
   <ReferenceTargets [
     <ReferenceTarget { kind = "WikiPage" target = "references/resource-dsl/" }>
   ]>

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.documents apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.documents envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Resource documents, package catalogs and KindDefinition contracts."
 } (

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.files apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.files envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Resource source shapes, VFS containment and file provenance."
 } (

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.index apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.index envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Resource DSL overview and progressive documentation index."
 } (

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.language apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.language envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "XNL language channels and authority projection rules."
 } (

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.migration apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.migration envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Migration guidance from non-canonical resource representations."
 } (

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

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.projections apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.projections envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Normalized, layered, content identity and dependency snapshot projections."
 } (

package/dist/system-skills/resource-dsl/WikiPages/skill-capsules/manifest.xnl

@@ -1,4 +1,4 @@
-<WikiPage #Halfcode.ResourceDsl.Wiki.skill-capsules apiVersion="halfcode.resources/v1" version="1.0.0" {
+<WikiPage #Halfcode.ResourceDsl.Wiki.skill-capsules envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "SkillCapsule dependencies, deterministic plans and atomic distribution."
 } (

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

@@ -7,7 +7,7 @@ catalog-owning manifest 可以直接使用由同一包 KindDefinitions 注册的
 推荐使用具名 Catalog；tag 固定 source shape，`resourceKind` 是发现资源的期望 Kind：
 
 ```xnl
-<SkillApp #demo.resource_workflow.authoring apiVersion="demo.resources/v1" version="1.0.0" (
+<SkillApp #demo.resource_workflow.authoring envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 (
   <Catalogs [
     <DirectoryResourceCatalog #kind_definitions {
       resourceKind = "KindDefinition"
@@ -34,12 +34,24 @@ catalog-owning manifest 可以直接使用由同一包 KindDefinitions 注册的
 `KindDefinition` 声明 source shape 与 descriptor contract：
 
 ```xnl
-<KindDefinition #halfcode.resource_kind.Function apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #halfcode.resource_kind.Function envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
+  resourceKind = "Function"
+  subjectFqn = "Halfcode.ResourceKind.Function"
   sourceShapes = ["single-file" "directory"]
-  currentApiVersion = "halfcode.resources/v1"
-  supportedApiVersions = ["halfcode.resources/v1"]
 } (
+  <SpecRevisions [
+    <SpecRevision #v1 {
+      specVersion = 1
+      schemaRef = "vfs://./spec-v1.schema.json"
+      schemaFingerprint = "sha256:<exact-schema-digest>"
+      contractFingerprint = "sha256:<exact-full-contract-digest>"
+      semanticValidatorFingerprint = "sha256:<exact-validator-digest>"
+      referenceProjectionFingerprint = "sha256:<exact-reference-projection-digest>"
+      compilerInputFingerprint = "sha256:<exact-compiler-input-digest>"
+      stability = "stable"
+    }>
+  ]>
   <DescriptorContract (
     <Identity { required = true form = "fqn" }>
     <CodeBinding { property = "src" scheme = "vfs" exportFragmentRequired = true }>
@@ -48,20 +60,20 @@ catalog-owning manifest 可以直接使用由同一包 KindDefinitions 注册的
 )>
 ```
 
-`currentApiVersion` 是新资源和迁移目标版本，`supportedApiVersions` 是 loader 可直接读取的兼容集合，且必须包含 current。未知版本必须先经过调用方在代码侧注册的确定性 migration，再交给 loader；可执行转换不写入 XNL。
+`SpecRevision.specVersion` 是 exact writer revision，不表示“当前”或范围。schema、semantic contract 和外层 `sourceShapes`/`documentCardinality`/`requiredFiles` 共同进入 contract identity；任何一项改变都要求新的 `specVersion`。reader compatibility 与 source migration 是两条独立链路：前者只生成 resolved projection 和 receipt，后者显式重写 authoring source。
 
 `documentCardinality` 缺省为 `"one"`。只有 `sourceShapes = ["single-file"]` 的 Kind 可以声明 `documentCardinality = "many"`，表示一个 authority 文档允许包含多个并列的同 Kind 根；它不是对所有 XNL 文件放宽根约束。
 
-Kind contract 可以按自身语义约束 lifecycle、description、instruction、code binding 与 includes；除 `#id` 和 `apiVersion` 外，这些字段都不是通用 loader 强加给所有 Kind 的共同要求。
+Kind contract 可以按自身语义约束 lifecycle、description、instruction、code binding 与 includes；除 `#id`、`envelopeVersion` 和 writer `specVersion` 外，这些字段都不是通用 loader 强加给所有 Kind 的共同要求。
 
-加载成功后，consumer 从 `ResourceTree.registry.kindDefinitions` 按 `resourceKind` 取得规范化 contract。该 projection 包含 version、source shape、cardinality、required files 以及 KindDefinition 自身的 `resourceId`/`documentUri` provenance；KindDefinition 不混入业务资源的 `registry.byKind`。
+加载成功后，consumer 从 `AuthoredResourceTree.registry.kindDefinitions` 按 `resourceKind` 取得规范化 contract。KindDefinition authority 本身也作为 authored record 进入 `registry.byKind`；resolution 使用 compiler-owned exact core reader 为它生成普通 receipt，不存在无审计的 bootstrap 分支。
 
 ## Resource descriptor
 
 descriptor 根 tag 直接使用 kind，`#id` 是资源 FQN。唯一概念进入 `()`；重复成员进入 `[]`：
 
 ```xnl
-<Function #demo.resource_workflow.prepare_data apiVersion="halfcode.resources/v1" version="1.0.0" {
+<Function #demo.resource_workflow.prepare_data envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Active"
   title = "Prepare workflow data"
 } (
@@ -80,11 +92,11 @@ descriptor 根 tag 直接使用 kind，`#id` 是资源 FQN。唯一概念进入
 
 ```markdown
 ---
-apiVersion: demo.resources/v1
+envelopeVersion: halfcode.resource-envelope/v1
+specVersion: 1
 kind: ApplicationSOP
 metadata:
   fqn: Demo.ApplicationSOP.Search
-  version: 1.0.0
 spec:
   description: 执行搜索并返回结构化结果
 ---
@@ -92,20 +104,24 @@ spec:
 这里是 SOP 正文。
 ```
 
-frontmatter 只规范化 identity、metadata 与 JSON-compatible `spec`；正文不会被解释为 dependency 或额外 metadata。
+frontmatter 只规范化 identity、envelope、writer revision 与 JSON-compatible `spec`；正文不会被解释为 dependency 或额外 metadata。关闭 frontmatter 的 `---` 之后恰好一个分隔换行被移除，其余正文 code units（包括 LF/CRLF 与末尾换行）原样成为 `ResourceNode.text`/`AuthoredResourceSpec.text`，并由 resolution 携带到 resolved node。
 
 目录资源可以通过 `readResourceMaterial` 读取显式 `vfs://./` material。该 API 只接受 canonical loader 产生的 authentic tree，重复校验 authority provenance、directory owner boundary、symlink 与 regular-file 约束，并返回 bytes、SHA-256 digest、canonical source URI 和 typed contribution。它不解释 material 内容，也不执行代码；语言 runtime 和叶子资源接纳由 consumer 拥有。
 
-允许 forest 的 Kind 仍逐根执行同样的 kind、identity 与 `apiVersion` 校验。例如 Decision Kind 可以显式声明：
+允许 forest 的 Kind 仍逐根执行同样的 kind、identity、envelope 与 writer revision 校验。例如 Decision Kind 可以显式声明：
 
 ```xnl
-<KindDefinition #codument.resource_kind.Decision apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #codument.resource_kind.Decision envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
+  resourceKind = "Decision"
+  subjectFqn = "Codument.ResourceKind.Decision"
   sourceShapes = ["single-file"]
-  currentApiVersion = "codument.tech/v1alpha1"
-  supportedApiVersions = ["codument.tech/v1alpha1"]
   documentCardinality = "many"
-}>
+} (
+  <SpecRevisions [
+    <SpecRevision #v1 { specVersion = 1 schemaRef = "vfs://./spec-v1.schema.json" /* exact fingerprints omitted */ }>
+  ]>
+)>
 ```
 
 对应 authority 文件可以有多个并列 `<Decision ...>` 根。每个根归一化为独立 resource record，并共享该文件的 `documentUri` provenance；重复 `#id`、混合根 kind 或不受支持的版本仍是错误。
@@ -115,7 +131,7 @@ frontmatter 只规范化 identity、metadata 与 JSON-compatible `spec`；正文
 mapping 根拥有多个唯一 collection subdomain；collection 的 `[]` 承载重复条目：
 
 ```xnl
-<ResourceMappings #demo.resource_workflow.mappings apiVersion="halfcode.resources/v1" version="1.0.0" (
+<ResourceMappings #demo.resource_workflow.mappings envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 (
   <ReferenceTargets [
     <ReferenceTarget #function_dependency {
       fromKind = "Function"

package/dist/system-skills/resource-dsl/examples/function.xnl

@@ -1,4 +1,4 @@
-<Function #demo.resource_workflow.prepare_data apiVersion="halfcode.resources/v1" version="1.0.0" {
+<Function #demo.resource_workflow.prepare_data envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Active"
   title = "Prepare workflow data"
 } (

package/dist/system-skills/resource-dsl/examples/kind-definition.xnl

@@ -1,9 +1,21 @@
-<KindDefinition #halfcode.resource_kind.Function apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #halfcode.resource_kind.Function envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
+  resourceKind = "Function"
+  subjectFqn = "Halfcode.ResourceKind.Function"
   sourceShapes = ["single-file" "directory"]
-  currentApiVersion = "halfcode.resources/v1"
-  supportedApiVersions = ["halfcode.resources/v1"]
 } (
+  <SpecRevisions [
+    <SpecRevision #v1 {
+      specVersion = 1
+      schemaRef = "vfs://./spec-v1.schema.json"
+      schemaFingerprint = "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+      contractFingerprint = "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+      semanticValidatorFingerprint = "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+      referenceProjectionFingerprint = "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+      compilerInputFingerprint = "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      stability = "stable"
+    }>
+  ]>
   <DescriptorContract (
     <Identity { required = true form = "fqn" }>
     <CodeBinding { property = "src" scheme = "vfs" exportFragmentRequired = true }>

package/dist/system-skills/resource-dsl/examples/resource-mappings.xnl

@@ -1,4 +1,4 @@
-<ResourceMappings #demo.resource_workflow.mappings apiVersion="halfcode.resources/v1" version="1.0.0" (
+<ResourceMappings #demo.resource_workflow.mappings envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 (
   <ReferenceTargets [
     <ReferenceTarget #function_dependency {
       fromKind = "Function"

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

@@ -1,4 +1,4 @@
-<ResourcePackage #demo.resource_workflow.authoring apiVersion="halfcode.resources/v1" version="1.0.0" {
+<ResourcePackage #demo.resource_workflow.authoring envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Active"
   description = "Demo authoring resource package"
 } (

package/dist/system-skills/resource-dsl/examples/skill-capsule-authoring.xnl

@@ -1,4 +1,4 @@
-<SkillCapsule #example.resource_lifecycle.skill.authoring apiVersion="halfcode.resources/v1" version="1.0.0" {
+<SkillCapsule #example.resource_lifecycle.skill.authoring envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   name = "example-resource-lifecycle-authoring"
   lifecycle = "Active"
   description = "Generic operations for resource creation and revision."

package/dist/system-skills/resource-dsl/examples/skill-capsule-devops.xnl

@@ -1,4 +1,4 @@
-<SkillCapsule #example.resource_lifecycle.skill.devops apiVersion="halfcode.resources/v1" version="1.0.0" {
+<SkillCapsule #example.resource_lifecycle.skill.devops envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   name = "example-resource-lifecycle-devops"
   lifecycle = "Active"
   description = "Generic lifecycle root that routes authoring and run operations."

package/dist/system-skills/resource-dsl/examples/skill-capsule-kind-definition.xnl

@@ -1,11 +1,22 @@
-<KindDefinition #halfcode.resource_kind.SkillCapsule apiVersion="halfcode.resources/v1" version="1.0.0" {
+<KindDefinition #halfcode.resource_kind.SkillCapsule envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Versioned Skill capsule with exact sibling dependencies."
   resourceKind = "SkillCapsule"
+  subjectFqn = "Halfcode.ResourceKind.SkillCapsule"
   sourceShapes = ["directory"]
-  currentApiVersion = "halfcode.resources/v1"
-  supportedApiVersions = ["halfcode.resources/v1"]
 } (
+  <SpecRevisions [
+    <SpecRevision #v1 {
+      specVersion = 1
+      schemaRef = "vfs://./spec-v1.schema.json"
+      schemaFingerprint = "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+      contractFingerprint = "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+      semanticValidatorFingerprint = "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+      referenceProjectionFingerprint = "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+      compilerInputFingerprint = "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+      stability = "stable"
+    }>
+  ]>
   <DescriptorContract (
     <RequiredFiles [
       <File { name = "SKILL.metadata.yaml" }>

package/dist/system-skills/resource-dsl/examples/skill-capsule-resource-dsl.xnl

@@ -1,4 +1,4 @@
-<SkillCapsule #example.resource_lifecycle.skill.resource_dsl apiVersion="halfcode.resources/v1" version="1.0.0" {
+<SkillCapsule #example.resource_lifecycle.skill.resource_dsl envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   name = "example-resource-lifecycle-dsl"
   lifecycle = "Stable"
   description = "Shared resource DSL reference used by authoring operations."

package/dist/system-skills/resource-dsl/examples/skill-capsule-run.xnl

@@ -1,4 +1,4 @@
-<SkillCapsule #example.resource_lifecycle.skill.run apiVersion="halfcode.resources/v1" version="1.0.0" {
+<SkillCapsule #example.resource_lifecycle.skill.run envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   name = "example-resource-lifecycle-run"
   lifecycle = "Active"
   description = "Generic operations for running an authored resource."

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

@@ -15,14 +15,14 @@
 一个节点的完整形态是：
 
 ```xnl
-<Tag #id apiVersion="halfcode.resources/v1" version="1.0.0" { properties } ( unique-subdomains ) [ repeated-or-ordered-members ]>
+<Tag #id envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 { properties } ( unique-subdomains ) [ repeated-or-ordered-members ]>
 ```
 
 | 通道 | 唯一职责 | 资源 DSL 用法 |
 |---|---|---|
 | `Tag` | 节点类别 | `ResourcePackage`、`KindDefinition`、`Function`、`ResourceMappings` 等资源 kind |
 | `#id` | 节点身份 | 可跨容器引用的 FQN；不从文件名推断 |
-| metadata 位 | 系统级版本 | `apiVersion`、`version` |
+| metadata 位 | 容器协议与 Kind writer revision | `envelopeVersion`、正整数 `specVersion` |
 | `{}` | 无序业务属性 | lifecycle、description、kind、src、root 等标量或内联结构 |
 | `()` | 每父节点唯一的命名子域 | `Catalogs`、`DescriptorContract`、`Instruction`、`CodeBinding` 等 |
 | `[]` | 直接、有序或可重复事实 | catalog 条目、mapping 条目、includes 等 |
@@ -41,11 +41,11 @@
 | [migration.md](migration.md) | XML authority 如何迁移，哪些做法被明确拒绝。 |
 | [examples/](examples/) | 由当前 `xnl-core` parser 验证的规范实例。 |
 
-KindDefinition 同时拥有资源版本契约：`currentApiVersion` 指向当前 authoring 版本，`supportedApiVersions` 列出可直接加载的兼容版本。版本转换由 `halfcode-compiler.xnl/kind-definition` 的代码侧 migration registry 执行，XNL 不承载可执行转换。成功加载的规范化 contract 可从 `ResourceTree.registry.kindDefinitions` 读取，consumer 无需再次解析 Kind XNL。
+KindDefinition 同时拥有精确资源契约：每个 `SpecRevision` 声明一个正整数 writer `specVersion` 及 schema、semantic、source-contract fingerprints；`sourceShapes`、cardinality 与 required files 也绑定进该 revision 的 contract identity。Host 选择 exact reader revision 和 compatibility policy，resolution 只沿显式登记、唯一的 writer→reader 路径运行并生成 receipt。成功加载的规范化 contract 可从 `AuthoredResourceTree.registry.kindDefinitions` 读取，consumer 无需再次解析 Kind XNL。
 
-多个 package 的组合不产生新的 authoring authority。canonical loader 在同一次 raw-byte read 中产生 `LoadedResourceTree.contentIdentities`；`resolveEffectiveResourceContentIdentities()` 再从 exact effective layer 选择 authority identity 并合并 Kind owner 的显式 digest contributions。`EffectiveResourceRegistry` 和 `ResourceDependencySnapshot` 都是由已验证 XNL、显式 tombstone、typed edge 与 digest contribution 重建的只读投影；它们不得被序列化回 XNL 作为第二份事实源。完整规则见 [projections.md](projections.md)。
+多个 package 的组合不产生新的 authoring authority。canonical loader 在同一次 raw-byte read 中产生 `AuthoredResourceTree.contentIdentities`；Host 通过 exact reader profile 将 authored tree 解析为带 receipts 的 `ResolvedResourceTree`。`resolveEffectiveResourceContentIdentities()` 再从 exact effective authored layer 选择 authority identity 并合并 Kind owner 的显式 digest contributions。`EffectiveResourceRegistry` 和 `ResourceDependencySnapshot` 都是由已验证 authority、显式 tombstone、typed edge 与 digest contribution 重建的只读投影；它们不得被序列化回 XNL 作为第二份事实源。完整规则见 [projections.md](projections.md)。
 
-本目录自身也是 `Halfcode.ResourceDsl.Package@1.0.0`：XNL descriptors 只登记 canonical Markdown/XNL materials，不复制正文。`Halfcode.ResourceDsl.Skill.System` 编译为 `sys-halfcode-resource-dsl@1.0.0`，供离线消费者按需加载这些文档；每个 capsule 的 `references/.halfcode/provenance.json` 绑定 source FQN/apiVersion/version、生成协议和 payload digests。
+本目录自身也是 `Halfcode.ResourceDsl.Package@1.0.0`：XNL descriptors 只登记 canonical Markdown/XNL materials，不复制正文。`Halfcode.ResourceDsl.Skill.System` 编译为 `sys-halfcode-resource-dsl@1.0.0`，供离线消费者按需加载这些文档；每个 capsule 的 `references/.halfcode/provenance.json` 绑定 source FQN、`envelopeVersion`、writer `specVersion`、独立 Skill version、生成协议和 payload digests。
 
 ## 暂缓边界
 

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

@@ -5,9 +5,9 @@
 - 根 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` 注册纯转换函数，得到唯一版本链后再加载目标文档。
+- `envelopeVersion` 与正整数 writer `specVersion` 写在 metadata 位；title、lifecycle、description 等业务数据若属于该 Kind，则写入 `{}`。
+- 通用资源边界要求根 `#id`、固定 `envelopeVersion="halfcode.resource-envelope/v1"` 与已登记的 writer `specVersion`。`lifecycle`、`description` 的存在性和语义由具体 Kind 或 consumer contract 决定，resource-core 不提供虚假默认值。
+- 每个 KindDefinition 显式声明 `subjectFqn` 与一个或多个 exact `SpecRevision`。Host 选择 reader profile；`exact` 只接受同 revision，`backward` 系列只接受较旧 writer，并且只沿显式、唯一 resolution path 读取。source migration 是独立的 authoring 操作，不能伪装成 reader compatibility。
 - XNL authority 默认单根。只有 source shape 严格为 `single-file` 的 Kind 可以通过 `documentCardinality = "many"` 授权同 Kind forest；每个顶层根仍是独立资源，`[]` 继续只表达节点内部的重复子项。
 - 静态描述数据由所属节点自持，不寄存在另一域再引用回来。
 
@@ -16,7 +16,7 @@
 `()` 表示父节点拥有的唯一子域概念。同一父节点的 `()` 中，同名 tag 只能出现一次。重复条目由复数子域的 `[]` 承载：
 
 ```xnl
-<ResourcePackage #demo.package (
+<ResourcePackage #demo.package envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 (
   <Catalogs [
     <Catalog #functions { kind = "Function" root = "vfs://./Functions/" entry = "manifest.xnl" }>
     <Catalog #skills { kind = "SkillCapsule" root = "vfs://./Skills/" entry = "manifest.xnl" }>
@@ -43,15 +43,17 @@
 ## Authoring 与 projection
 
 ```text
-XNL authority document
+XNL/Markdown authority document
   -> xnl-core node tree
-  -> validated normalized resource descriptor + provenance
-  -> registry / mapping / application assembly projections
+  -> AuthoredResourceTree + authority provenance
+  -> exact reader resolution + receipts
+  -> ResolvedResourceTree / application projections
 ```
 
 - authority：磁盘上的 `.xnl` 文档；唯一可编辑事实。
 - parser tree：语法投影，只由 resource-core loader 消费。
-- normalized descriptor：稳定领域边界，携带 `resourceId`、`kind`、metadata、members、subdomains、`documentUri`、`logicalPath`；Kind-owned 可选属性保持存在或缺失的原始事实。
+- authored descriptor：稳定 writer 边界，携带 `resourceId`、`kind`、`envelopeVersion`、writer `specVersion`、members、subdomains、可选 Markdown `text`、`documentUri`、`logicalPath`；Kind-owned 可选属性保持存在或缺失的原始事实。
+- resolved descriptor：由 exact reader registration 产生，保留 authored source，并携带 writer/reader/path fingerprints 和 effective content digest；它不是新的 authoring authority。
 - consumer projection：可重建；不得暴露 parser node 内部字段，也不得反写 authority。
 
 package provenance 从 package manifest、document URI 与 logical path 派生。descriptor 不重复保存一份可由路径计算的 package identity。

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

@@ -1,4 +1,4 @@
-<ResourcePackage #Halfcode.ResourceDsl.Package apiVersion="halfcode.resources/v1" version="1.0.0" {
+<ResourcePackage #Halfcode.ResourceDsl.Package envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
   lifecycle = "Stable"
   description = "Canonical Halfcode Resource DSL documentation and consumer Skill resources."
 } (

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

@@ -8,7 +8,7 @@
 |---|---|
 | 根 element 名 | 根 tag（resource kind） |
 | `Id`/`Name` 等身份 attribute | 根 `#id` FQN；display name 若存在则留在 `{}` |
-| `Version`/schema version | metadata 位的 `version`/`apiVersion` |
+| `Version`/schema version | 固定 `envelopeVersion` + Kind-owned 正整数 writer `specVersion`；业务 SemVer 留在所属 Kind 字段 |
 | 普通 attributes | `{}` 中归节点所有的属性 |
 | 唯一 child section | `()` 中的唯一子域 |
 | 重复 child elements | 父 `[]` 或复数子域的 `[]` |
@@ -18,12 +18,13 @@
 ## 顺序
 
 1. 用 `KindDefinition` 明确 kind contract。
-   - 声明 `currentApiVersion` 与 `supportedApiVersions`。
-   - 对不可直接兼容的历史版本，在代码侧 `ResourceMigrationRegistry` 注册唯一纯转换链；XNL 不内嵌 transformer。
+   - 声明 `subjectFqn`、source/cardinality/required-file contract 与 exact `SpecRevisions` fingerprints。
+   - reader resolution 只负责把 immutable authored writer spec 投影到显式 reader revision；需要改变 authority 时，单独执行可审计的 source-migration 操作。XNL 不内嵌 transformer。
 2. 将 package/catalog authority 改为 XNL。
 3. 逐个资源按领域语义分配 `{}`、`()`、`[]`，保留稳定 `#id`。
 4. 将路径与代码引用规范为 VFS URI。
 5. 通过 resource-core 得到 normalized descriptor，再迁移 consumer。
+   - loader 产出 `AuthoredResourceTree`；Host 通过 exact reader profile 产出带普通 receipts 的 `ResolvedResourceTree`。
 6. 删除兼容 XML 与 `fast-xml-parser`，以产品 XML inventory 清零作为关闭条件。
 
 ## 明确拒绝
@@ -33,6 +34,8 @@
 - 根据目录名/文件名猜 kind 或 identity。
 - 在 XNL 内嵌函数、闭包或可执行表达式字符串。
 - 用无语义的 wrapper 模拟 XML 层级。
+- 把 reader/package 版本当成 writer `specVersion`，或让 `backward` reader 接受比自身更新的 writer。
+- 在同一字段中混用 resource envelope、Kind spec revision 与业务 SemVer。
 - 在 BusinessObject/PageObject API 尚未稳定时提前设计二者的专用 XNL schema。
 
 ## 暂时兼容

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

@@ -6,21 +6,22 @@
 
 | Fact | Authority owner | Halfcode projection |
 |---|---|---|
-| package、Catalog、KindDefinition、resource descriptor | XNL ResourcePackage | `LoadedResourceTree extends ResourceTree` |
+| package、Catalog、KindDefinition、resource descriptor | XNL/Markdown authority | `AuthoredResourceTree` |
+| reader selection、resolution path 与 effective spec | Host exact reader profile + admitted compiler/Kind registrations | `ResolvedResourceTree` + receipts |
 | 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` |
+| authority bytes | canonical loader 的同一次 raw-byte read | `AuthoredResourceTree.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 真源。
+`AuthoredResourceTree` 是单个已验证 package 的 writer projection；`ResolvedResourceTree` 保留该 authored source，并为 manifest、KindDefinition 与业务 resource 记录 writer/reader/path receipt。`EffectiveResourceRegistry` 只是多个 authored tree 的确定性只读投影；它会 deep-clone/freeze record、metadata、node/value 与 KindDefinition facts，避免调用方之后修改输入而改变既有投影。`ResourceDependencySnapshot` 又是某组 roots 在一个 content-sensitive registry revision 上的冻结闭包。所有 projection 都可由 authority facts 和显式 registrations 重建，不得反写任一 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 之前绑定。
+layer 只包含一个不透明、稳定的 `id` 和一个已验证 `AuthoredResourceTree`。数组从低 precedence 到高 precedence 排列，后一个 layer 优先。Halfcode 不保留特殊 layer 名称，不根据名称重排，也不拥有任何产品安装目录或机器路径策略；实际 roots 由 consumer 在调用 resource-core 之前绑定。
 
 组合规则是：
 
@@ -56,9 +57,9 @@ const registry = composeLayeredResourceRegistry({
 
 ## 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` 独立。
+canonical loader 对每个 XNL/Markdown authority 文件只读取一次 raw bytes：同一次读取同时用于 fatal UTF-8 decode、parse 和 SHA-256。成功加载后返回 `AuthoredResourceTree`；其 `contentIdentities` 精确覆盖 `registry.byKind` 的 KindDefinition 与业务 resources，不包含 package manifest。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 显式提供。
+只有 canonical loader 返回并由当前 runtime 登记的 authentic `AuthoredResourceTree` 才能进入 `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。
 

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

@@ -2,14 +2,14 @@
 
 ## 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 继续兼容；新资源不得采用该兼容路径。
+`SkillCapsule` descriptor 由 XNL 根节点拥有 FQN、consumer-facing `name`、resource `envelopeVersion` 与 writer `specVersion`。`SKILL.metadata.yaml` 拥有独立的 Skill SemVer 和 title/description 等呈现字段；它不重复 XNL name。若 descriptor 已声明 `name` 而 YAML 仍重复该字段，assembly 在 compiler 写入前以 `SKILL_CAPSULE_NAME_DUPLICATE` 失败。
 
-XNL `version` 也是 capsule identity 与 dependency binding 的唯一 version authority。历史 YAML 若仍带 `version`，必须与 XNL 严格相等，否则 assembly 以 `SKILL_CAPSULE_VERSION_CONFLICT` 失败。
+Skill dependency binding 使用 YAML 的 Skill SemVer；它与 resource writer `specVersion` 是两个正交维度，不能互相推导。provenance 同时记录 envelope/writer revision 与 Skill version。
 
 ```xnl
 <SkillCapsule #example.resource_lifecycle.skill.authoring
-  apiVersion="halfcode.resources/v1"
-  version="1.0.0" {
+  envelopeVersion="halfcode.resource-envelope/v1"
+  specVersion=1 {
   name = "example-resource-authoring"
   description = "Generic resource authoring operations."
 } (
@@ -18,11 +18,12 @@ XNL `version` 也是 capsule identity 与 dependency binding 的唯一 version a
 )>
 ```
 
-对应 YAML 只保存呈现字段：
+对应 YAML 保存 Skill-owned version 与呈现字段：
 
 ```yaml
 title: Example Resource Authoring
 description: Generic resource authoring operations.
+version: 1.0.0
 ```
 
 ## `SkillDependencies` 与 `Includes`
@@ -62,7 +63,7 @@ resource DSL -> authoring -> devops/root
 - `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 字段。
+完整 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 由 XNL 声明，Skill version 由 YAML 声明，dependency 精确绑定 `1.0.0`。
 
 ## Deterministic plan 与 atomic apply
 
@@ -74,7 +75,7 @@ resource DSL -> authoring -> devops/root
 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。
+每个 planned capsule 还必须包含固定路径 `references/.halfcode/provenance.json`。该文件由 compiler 生成，不由模板维护；它记录 `halfcode.skill-provenance/v1` format、`halfcode.skill-distribution/v1` generator、SkillCapsule source 的 FQN/`envelopeVersion`/writer `specVersion`、独立 Skill version，以及除自身以外全部 payload files 的 canonical path/content digest。manifest 自身作为普通 planned file 进入 capsule/closure digest，因此不需要自引用摘要。applier 会在任何目标写入前从 plan 重建并 exact 校验这些 facts。
 
 ```ts
 const plan = await planSkillCapsuleDistribution({