halfcode-compiler.xnl 0.2.1 → 0.2.3

package/dist/{src-4m42imop.js → src-DRIws6tY.js}

@@ -1,4 +1,4 @@
-import { n as loadResourceTree } from "./src-DKkIFGWH.js";
+import { n as loadResourceTree } from "./src-DCRih45n.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";
@@ -193,6 +193,7 @@ async function resolveApplicationAssembly(options) {
 		pageObjects: loaded.flatMap((module) => module.pageObjects),
 		byFqn
 	};
+	assertSkillDependencyBindings(assembly.skillCapsules, byFqn);
 	setObjectOperationCompilations(assembly, compilations);
 	return assembly;
 }
@@ -385,22 +386,61 @@ async function readTextResource(module, record, kind) {
 	};
 }
 async function readSkillCapsule(module, record) {
-	const metadata = await readRequiredMaterial(module, record, "SkillMetadata");
+	const metadataMaterial = await readRequiredMaterial(module, record, "SkillMetadata");
 	const template = await readRequiredMaterial(module, record, "Template");
+	const version = record.metadata.version;
+	const apiVersion = record.metadata.apiVersion;
+	if (!apiVersion) throw new Error(`SKILL_CAPSULE_API_VERSION_MISSING: ${record.logicalPath} is missing XNL metadata apiVersion`);
+	if (!version) throw new Error(`SKILL_CAPSULE_VERSION_MISSING: ${record.logicalPath} is missing XNL metadata version`);
+	const parsedMetadata = parse(metadataMaterial.content);
+	if (!parsedMetadata || typeof parsedMetadata !== "object" || Array.isArray(parsedMetadata)) throw new Error(`SKILL_CAPSULE_METADATA_INVALID: ${record.logicalPath} Skill metadata must be a YAML object`);
+	const yamlVersion = parsedMetadata.version;
+	if (yamlVersion !== void 0 && yamlVersion !== version) throw new Error(`SKILL_CAPSULE_VERSION_CONFLICT: ${requiredFqn(record)} YAML version ${JSON.stringify(yamlVersion)} does not match XNL version ${version}`);
+	const hasXnlName = Object.prototype.hasOwnProperty.call(record.node.properties, "name");
+	const xnlName = stringResourceValue(record.node.properties.name);
+	if (hasXnlName && !xnlName) throw new Error(`SKILL_CAPSULE_NAME_INVALID: ${requiredFqn(record)} XNL name must be a non-empty string`);
+	if (hasXnlName && Object.prototype.hasOwnProperty.call(parsedMetadata, "name")) throw new Error(`SKILL_CAPSULE_NAME_DUPLICATE: ${requiredFqn(record)} name is owned by XNL and must not be repeated in YAML`);
 	return {
 		kind: "SkillCapsule",
 		fqn: requiredFqn(record),
+		...xnlName ? { name: xnlName } : {},
+		apiVersion,
+		version,
 		description: requiredDescription(record),
-		metadata: parse(metadata.content),
+		metadata: {
+			...parsedMetadata,
+			version
+		},
 		template,
 		resourceMappings: await readOptionalMaterial(module, record, "ResourceMappings"),
 		includes: nodeMembers(record.node.subdomains.Includes).filter((node) => node.tag === "Include").map((include) => ({
 			kind: requiredNodeProperty(include, "kind", record),
 			ref: requiredNodeProperty(include, "ref", record)
 		})),
+		dependencies: nodeMembers(record.node.subdomains.SkillDependencies).filter((node) => node.tag === "SkillDependency").map((dependency) => {
+			const ref = requiredNodeProperty(dependency, "ref", record);
+			return {
+				ref,
+				fqn: resourceRefToFqn(ref),
+				version: requiredNodeProperty(dependency, "version", record)
+			};
+		}),
 		source: sourceFor(module, record)
 	};
 }
+function assertSkillDependencyBindings(skills, byFqn) {
+	for (const skill of skills) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const dependency of skill.dependencies) {
+			if (seen.has(dependency.fqn)) throw new Error(`SKILL_DEPENDENCY_DUPLICATE: ${skill.fqn} declares ${dependency.fqn} more than once`);
+			seen.add(dependency.fqn);
+			const target = byFqn.get(dependency.fqn);
+			if (!target) throw new Error(`SKILL_DEPENDENCY_MISSING: ${skill.fqn} dependency ${dependency.ref} does not exist`);
+			if (target.kind !== "SkillCapsule") throw new Error(`SKILL_DEPENDENCY_KIND_MISMATCH: ${skill.fqn} dependency ${dependency.ref} targets ${target.kind}`);
+			if (target.version !== dependency.version) throw new Error(`SKILL_DEPENDENCY_VERSION_MISMATCH: ${skill.fqn} dependency ${dependency.ref} expected ${dependency.version} but found ${target.version}`);
+		}
+	}
+}
 async function readOptionalMaterial(module, record, childName) {
 	const child = record.node.subdomains[childName];
 	if (!child) return void 0;

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

@@ -0,0 +1,21 @@
+<KindDefinition #Halfcode.ResourceDsl.KindDefinition.SkillCapsule apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Kind definition for the versioned Resource DSL consumer SkillCapsule."
+  resourceKind = "SkillCapsule"
+  sourceShapes = ["directory"]
+  currentApiVersion = "halfcode.resources/v1"
+  supportedApiVersions = ["halfcode.resources/v1"]
+} (
+  <DescriptorContract (
+    <RequiredFiles [
+      <File { name = "SKILL.metadata.yaml" }>
+      <File { name = "SKILL.template.ejs" }>
+      <File { name = "resource-mappings.xnl" }>
+    ]>
+    <IncludeContract {
+      collection = "Includes"
+      relation = "compiled-resource-selection"
+      dependencySemantics = false
+    }>
+  )>
+)>

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

@@ -0,0 +1,10 @@
+<KindDefinition #Halfcode.ResourceDsl.KindDefinition.WikiPage apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Kind definition for canonical documentation pages referenced from the Resource DSL package root."
+  resourceKind = "WikiPage"
+  sourceShapes = ["directory"]
+  currentApiVersion = "halfcode.resources/v1"
+  supportedApiVersions = ["halfcode.resources/v1"]
+} (
+  <DescriptorContract>
+)>

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

@@ -0,0 +1,2 @@
+title: Halfcode Resource DSL
+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/SKILL.template.ejs

@@ -0,0 +1,20 @@
+---
+name: <%= metadata.name %>
+description: <%= metadata.description %>
+---
+
+# <%= metadata.title %>
+
+Use this Skill for the generic XNL resource language and its deterministic compiler contracts. Product-specific authoring and runtime operations belong to their owner Skills.
+
+## Progressive loading
+
+1. Start with `references/resource-dsl/index.md`.
+2. For XNL channels and source syntax, read `references/resource-dsl/language.md` and only the needed file under `references/resource-dsl/examples/`.
+3. For ResourcePackage, Catalog or KindDefinition work, read `references/resource-dsl/documents.md` and `references/resource-dsl/files.md`.
+4. For layered registries, content identities or snapshots, read `references/resource-dsl/projections.md`.
+5. For SkillCapsule dependency/distribution work, read `references/resource-dsl/skill-capsules.md`.
+6. Read `references/resource-dsl/migration.md` only for migration work.
+7. Use `references/.halfcode/provenance.json` to verify source identity, version and payload digests.
+
+Do not infer resource relationships from ordinary text. Use explicit catalogs, typed references and Kind-owned contracts, then rely on deterministic validation and compilation.

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

@@ -0,0 +1,18 @@
+<SkillCapsule #Halfcode.ResourceDsl.Skill.System apiVersion="halfcode.resources/v1" version="1.0.0" {
+  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."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+  <ResourceMappings { href = "vfs://./resource-mappings.xnl" format = "xnl" }>
+  <Includes [
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.index" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.language" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.documents" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.files" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.projections" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.skill-capsules" }>
+    <Include { kind = "WikiPage" ref = "resource://Halfcode.ResourceDsl.Wiki.migration" }>
+  ]>
+)>

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

@@ -0,0 +1,10 @@
+<ResourceMappings #Halfcode.ResourceDsl.ResourceMappings.System apiVersion="halfcode.resources/v1" version="1.0.0" (
+  <ReferenceTargets [
+    <ReferenceTarget { kind = "WikiPage" target = "references/resource-dsl/" }>
+  ]>
+  <SourceRoots [
+    <SourceRoot #CanonicalExamples { sourceRoot = "vfs://module/ResourceDsl/" } [
+      <CopyDirectory { from = "examples" to = "references/resource-dsl/examples" }>
+    ]>
+  ]>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.documents apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Resource documents, package catalogs and KindDefinition contracts."
+} (
+  <Instruction { href = "vfs://@/documents.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.files apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Resource source shapes, VFS containment and file provenance."
+} (
+  <Instruction { href = "vfs://@/files.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.index apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Resource DSL overview and progressive documentation index."
+} (
+  <Instruction { href = "vfs://@/index.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.language apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "XNL language channels and authority projection rules."
+} (
+  <Instruction { href = "vfs://@/language.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.migration apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Migration guidance from non-canonical resource representations."
+} (
+  <Instruction { href = "vfs://@/migration.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.projections apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Normalized, layered, content identity and dependency snapshot projections."
+} (
+  <Instruction { href = "vfs://@/projections.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,6 @@
+<WikiPage #Halfcode.ResourceDsl.Wiki.skill-capsules apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "SkillCapsule dependencies, deterministic plans and atomic distribution."
+} (
+  <Instruction { href = "vfs://@/skill-capsules.md" format = "markdown" }>
+)>

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

@@ -0,0 +1,119 @@
+# Resource Document Families
+
+## ResourcePackage 与 Catalogs
+
+一个 package 有且只有一个 `ResourcePackage` authority root。它拥有唯一 `Catalogs` 子域；每个 `Catalog` 声明一种资源的逻辑根与目录入口：
+
+```xnl
+<ResourcePackage #demo.resource_workflow.authoring apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Active"
+  description = "Demo authoring resource package"
+} (
+  <Catalogs [
+    <Catalog #kind_definitions {
+      kind = "KindDefinition"
+      shape = "directory"
+      root = "vfs://./KindDefinitions/"
+      entry = "manifest.xnl"
+    }>
+    <Catalog #functions {
+      kind = "Function"
+      shape = "directory"
+      root = "vfs://./Functions/"
+      entry = "manifest.xnl"
+    }>
+  ]>
+)>
+```
+
+catalog 只描述组织，不复制每个 descriptor 的内容。`shape` 取 `single-file|directory|manifest`；后两者必须声明目录入口 `entry`。`single-file` 缺省扫描 `root` 下全部 `.xnl` 文件，也可以用可选 `entry = "<name>.xnl"` 精确选择同目录中的一个 authority 文件；该 entry 必须是无路径片段的 XNL 文件名。loader 用根 tag/`#id` 确认 kind/identity。
+
+## KindDefinition
+
+`KindDefinition` 声明 source shape 与 descriptor contract：
+
+```xnl
+<KindDefinition #halfcode.resource_kind.Function apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  sourceShapes = ["single-file" "directory"]
+  currentApiVersion = "halfcode.resources/v1"
+  supportedApiVersions = ["halfcode.resources/v1"]
+} (
+  <DescriptorContract (
+    <Identity { required = true form = "fqn" }>
+    <CodeBinding { property = "src" scheme = "vfs" exportFragmentRequired = true }>
+    <Instruction { required = false source = "inline-or-vfs" }>
+  )>
+)>
+```
+
+`currentApiVersion` 是新资源和迁移目标版本，`supportedApiVersions` 是 loader 可直接读取的兼容集合，且必须包含 current。未知版本必须先经过调用方在代码侧注册的确定性 migration，再交给 loader；可执行转换不写入 XNL。
+
+`documentCardinality` 缺省为 `"one"`。只有 `sourceShapes = ["single-file"]` 的 Kind 可以声明 `documentCardinality = "many"`，表示一个 authority 文档允许包含多个并列的同 Kind 根；它不是对所有 XNL 文件放宽根约束。
+
+Kind contract 可以按自身语义约束 lifecycle、description、instruction、code binding 与 includes；除 `#id` 和 `apiVersion` 外，这些字段都不是通用 loader 强加给所有 Kind 的共同要求。
+
+加载成功后，consumer 从 `ResourceTree.registry.kindDefinitions` 按 `resourceKind` 取得规范化 contract。该 projection 包含 version、source shape、cardinality、required files 以及 KindDefinition 自身的 `resourceId`/`documentUri` provenance；KindDefinition 不混入业务资源的 `registry.byKind`。
+
+## Resource descriptor
+
+descriptor 根 tag 直接使用 kind，`#id` 是资源 FQN。唯一概念进入 `()`；重复成员进入 `[]`：
+
+```xnl
+<Function #demo.resource_workflow.prepare_data apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Active"
+  title = "Prepare workflow data"
+} (
+  <Instruction ?instruction>
+  接收输入并产生下游 procedure 所需的规范数据。
+  </?instruction>
+  <CodeBinding {
+    src = "vfs://@/apps/demo-resource-workflow-authoring/src/procedures.ts#prepareProcedure"
+  }>
+)>
+```
+
+通用资源外壳只规定 identity、metadata channel、members/subdomains 和 provenance。各 Kind 的稳定领域字段及其 requiredness 由对应 `KindDefinition` 或 consumer contract 收窄；缺失的可选字段不会被填成空字符串。
+
+允许 forest 的 Kind 仍逐根执行同样的 kind、identity 与 `apiVersion` 校验。例如 Decision Kind 可以显式声明：
+
+```xnl
+<KindDefinition #codument.resource_kind.Decision apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  sourceShapes = ["single-file"]
+  currentApiVersion = "codument.tech/v1alpha1"
+  supportedApiVersions = ["codument.tech/v1alpha1"]
+  documentCardinality = "many"
+}>
+```
+
+对应 authority 文件可以有多个并列 `<Decision ...>` 根。每个根归一化为独立 resource record，并共享该文件的 `documentUri` provenance；重复 `#id`、混合根 kind 或不受支持的版本仍是错误。
+
+## ResourceMappings
+
+mapping 根拥有多个唯一 collection subdomain；collection 的 `[]` 承载重复条目：
+
+```xnl
+<ResourceMappings #demo.resource_workflow.mappings apiVersion="halfcode.resources/v1" version="1.0.0" (
+  <ReferenceTargets [
+    <ReferenceTarget #function_dependency {
+      fromKind = "Function"
+      field = "dependsOn"
+      targetKind = "Function"
+    }>
+  ]>
+  <CallableArtifacts [
+    <CallableArtifact #function_callable {
+      kind = "Function"
+      binding = "CodeBinding.src"
+    }>
+  ]>
+  <SourceRoots [
+    <SourceRoot #authoring {
+      uri = "vfs://@/apps/demo-resource-workflow-authoring/resources/"
+    }>
+  ]>
+)>
+```
+
+mapping key 是显式属性或 `#id`，不得把用户数据动态拼进 tag 名。

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

@@ -0,0 +1,12 @@
+<Function #demo.resource_workflow.prepare_data apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Active"
+  title = "Prepare workflow data"
+} (
+  <Instruction ?instruction>
+  接收输入并产生下游 procedure 所需的规范数据。
+  </?instruction>
+  <CodeBinding {
+    src = "vfs://@/apps/demo-resource-workflow-authoring/src/procedures.ts#prepareProcedure"
+  }>
+)>
+

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

@@ -0,0 +1,17 @@
+# Parseable Examples
+
+> 目录职责 · holds: 由当前 xnl-core parser 机械验证的规范 resource DSL 样例 · excludes: demo 业务资源与运行态 fixtures · tier: stable · ⬆from: resource DSL 文档实例 · ⬇to: parser/loader contract tests
+
+| 文件 | 文档族 |
+|---|---|
+| `resource-package.xnl` | package 与 catalogs |
+| `kind-definition.xnl` | 通用 Function KindDefinition |
+| `skill-capsule-kind-definition.xnl` | SkillCapsule exact dependency contract |
+| `skill-capsule-devops.xnl` | 四 Skill 示例的 lifecycle root |
+| `skill-capsule-authoring.xnl` | authoring -> shared resource DSL dependency |
+| `skill-capsule-run.xnl` | 无 sibling dependency 的 run Skill |
+| `skill-capsule-resource-dsl.xnl` | 被 authoring 复用的 shared resource DSL Skill |
+| `function.xnl` | 带 instruction 与 code binding 的 descriptor |
+| `resource-mappings.xnl` | reference/callable/source-root mappings |
+
+这些文件由当前 `xnl-core` parser 做 parse/stringify/parse 验证。下游 resource-core track 会把相同检查变成持续测试。

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

@@ -0,0 +1,12 @@
+<KindDefinition #halfcode.resource_kind.Function apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  sourceShapes = ["single-file" "directory"]
+  currentApiVersion = "halfcode.resources/v1"
+  supportedApiVersions = ["halfcode.resources/v1"]
+} (
+  <DescriptorContract (
+    <Identity { required = true form = "fqn" }>
+    <CodeBinding { property = "src" scheme = "vfs" exportFragmentRequired = true }>
+    <Instruction { required = false source = "inline-or-vfs" }>
+  )>
+)>

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

@@ -0,0 +1,21 @@
+<ResourceMappings #demo.resource_workflow.mappings apiVersion="halfcode.resources/v1" version="1.0.0" (
+  <ReferenceTargets [
+    <ReferenceTarget #function_dependency {
+      fromKind = "Function"
+      field = "dependsOn"
+      targetKind = "Function"
+    }>
+  ]>
+  <CallableArtifacts [
+    <CallableArtifact #function_callable {
+      kind = "Function"
+      binding = "CodeBinding.src"
+    }>
+  ]>
+  <SourceRoots [
+    <SourceRoot #authoring {
+      uri = "vfs://@/apps/demo-resource-workflow-authoring/resources/"
+    }>
+  ]>
+)>
+

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

@@ -0,0 +1,19 @@
+<ResourcePackage #demo.resource_workflow.authoring apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Active"
+  description = "Demo authoring resource package"
+} (
+  <Catalogs [
+    <Catalog #kind_definitions {
+      kind = "KindDefinition"
+      shape = "directory"
+      root = "vfs://./KindDefinitions/"
+      entry = "manifest.xnl"
+    }>
+    <Catalog #functions {
+      kind = "Function"
+      shape = "directory"
+      root = "vfs://./Functions/"
+      entry = "manifest.xnl"
+    }>
+  ]>
+)>

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

@@ -0,0 +1,11 @@
+<SkillCapsule #example.resource_lifecycle.skill.authoring apiVersion="halfcode.resources/v1" version="1.0.0" {
+  name = "example-resource-lifecycle-authoring"
+  lifecycle = "Active"
+  description = "Generic operations for resource creation and revision."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+  <SkillDependencies [
+    <SkillDependency { ref = "resource://example.resource_lifecycle.skill.resource_dsl" version = "1.0.0" }>
+  ]>
+)>

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

@@ -0,0 +1,12 @@
+<SkillCapsule #example.resource_lifecycle.skill.devops apiVersion="halfcode.resources/v1" version="1.0.0" {
+  name = "example-resource-lifecycle-devops"
+  lifecycle = "Active"
+  description = "Generic lifecycle root that routes authoring and run operations."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+  <SkillDependencies [
+    <SkillDependency { ref = "resource://example.resource_lifecycle.skill.authoring" version = "1.0.0" }>
+    <SkillDependency { ref = "resource://example.resource_lifecycle.skill.run" version = "1.0.0" }>
+  ]>
+)>

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

@@ -0,0 +1,27 @@
+<KindDefinition #halfcode.resource_kind.SkillCapsule apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Versioned Skill capsule with exact sibling dependencies."
+  resourceKind = "SkillCapsule"
+  sourceShapes = ["directory"]
+  currentApiVersion = "halfcode.resources/v1"
+  supportedApiVersions = ["halfcode.resources/v1"]
+} (
+  <DescriptorContract (
+    <RequiredFiles [
+      <File { name = "SKILL.metadata.yaml" }>
+      <File { name = "SKILL.template.ejs" }>
+    ]>
+    <SkillDependencyContract {
+      collection = "SkillDependencies"
+      member = "SkillDependency"
+      refScheme = "resource"
+      targetKind = "SkillCapsule"
+      versionBinding = "exact"
+    }>
+    <IncludeContract {
+      collection = "Includes"
+      relation = "compiled-resource-selection"
+      dependencySemantics = false
+    }>
+  )>
+)>

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

@@ -0,0 +1,8 @@
+<SkillCapsule #example.resource_lifecycle.skill.resource_dsl apiVersion="halfcode.resources/v1" version="1.0.0" {
+  name = "example-resource-lifecycle-dsl"
+  lifecycle = "Stable"
+  description = "Shared resource DSL reference used by authoring operations."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+)>

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

@@ -0,0 +1,8 @@
+<SkillCapsule #example.resource_lifecycle.skill.run apiVersion="halfcode.resources/v1" version="1.0.0" {
+  name = "example-resource-lifecycle-run"
+  lifecycle = "Active"
+  description = "Generic operations for running an authored resource."
+} (
+  <SkillMetadata { href = "vfs://./SKILL.metadata.yaml" format = "yaml" }>
+  <Template { href = "vfs://./SKILL.template.ejs" format = "ejs" }>
+)>

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

@@ -0,0 +1,47 @@
+# Files And Bundles
+
+## 内容为真源
+
+kind 与 identity 来自文件根 tag 和 `#id`。目录名、文件名和 catalog 路径只是布局；扫描器不得通过后缀或目录名补写资源语义。
+
+## 两种定义形态
+
+- 单文件 definition：任意描述性 `.xnl` 文件名，文件内有一个语义根。
+- 目录 bundle：入口固定为 `manifest.xnl`，域文件使用描述性 `.xnl` 文件名。
+
+目录 bundle 示例：
+
+```text
+Functions/
+  PrepareData/
+    manifest.xnl       # <Function #demo.resource_workflow.prepare_data ...>
+    instruction.md     # CodeBinding/Instruction 引用的 material
+```
+
+`manifest.xnl` 的根决定 bundle kind 与 identity。独立子域可以从 manifest 的 `()` 原样外提为同型域文件；外提不改变 logical refs。
+
+## 单文件 forest
+
+单文件默认只有一个语义根。仅当对应 `KindDefinition` 同时声明 `sourceShapes = ["single-file"]` 与 `documentCardinality = "many"` 时，同一个 `.xnl` authority 文件才可以包含多个并列根。
+
+forest 的每个根是独立资源，必须使用同一 Kind，具有独立 `#id`，并通过该 Kind 的版本契约。`ResourcePackage`、catalog、KindDefinition 与目录 bundle 入口始终保持单根。
+
+## Provenance 与 logical path
+
+loader 为每个 normalized descriptor 附加只读 provenance：
+
+- `documentUri`：加载 authority 文档的 canonical VFS URI；
+- `logicalPath`：相对 package catalog root 的逻辑路径；
+- `packageId`：从 `ResourcePackage #id` 派生；
+- `resourceId`：来自 descriptor 根 `#id`。
+
+这些字段由 loader 拥有，author 不在 descriptor 中重复配置。consumer 可以记录 provenance 用于诊断，但不得修改后反写 XNL。
+
+## 扫描边界
+
+- 默认目录入口仅为 `manifest.xnl`。
+- `single-file` catalog 缺省扫描 root 下全部 `.xnl`；声明 `entry = "name.xnl"` 时只加载该文件，便于多个不同 Kind 共用一个物理目录。
+- 非入口 `.xnl` 文件只能作为显式域/物料被入口引用，不能被重复注册为第二资源。
+- 多根文档必须由 KindDefinition 显式授权；loader 不根据文件名或根数量猜测 forest 语义。
+- catalog root 必须是 `vfs://` URI。
+- resource-core 负责 URI 解析、边界检查和重复 identity 诊断；consumer 不自行扫描磁盘。

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

@@ -0,0 +1,59 @@
+# Halfcode XNL Resource DSL
+
+## 目录职责
+
+- **holds**：halfcode resource package、catalog、KindDefinition、descriptor、mapping、URI 与文件组织的 XNL authoring 真源。
+- **excludes**：parser/registry 实现（→`packages/resource-core/`）、consumer 归一化逻辑（→各 consumer package）、运行态数据与 BusinessObject/PageObject 尚未稳定的专用 API。
+- **tier**：`stable`
+- **promotes_from**：Codument track `define-xnl-resource-dsl` 的 proposal、design、behavior 与 modeling delta。
+- **promotes_to**：资源 authoring 文件、loader/validator、consumer contract tests 与公开文档。
+
+本目录定义 halfcode 资源的 XNL-native 语言。XNL 文档是可持久化语义真源；normalized descriptors、application assembly、发布制品和运行快照都是可重建投影，不得反向成为第二份 authoring 定义。
+
+## 核心公理
+
+一个节点的完整形态是：
+
+```xnl
+<Tag #id apiVersion="halfcode.resources/v1" version="1.0.0" { properties } ( unique-subdomains ) [ repeated-or-ordered-members ]>
+```
+
+| 通道 | 唯一职责 | 资源 DSL 用法 |
+|---|---|---|
+| `Tag` | 节点类别 | `ResourcePackage`、`KindDefinition`、`Function`、`ResourceMappings` 等资源 kind |
+| `#id` | 节点身份 | 可跨容器引用的 FQN；不从文件名推断 |
+| metadata 位 | 系统级版本 | `apiVersion`、`version` |
+| `{}` | 无序业务属性 | lifecycle、description、kind、src、root 等标量或内联结构 |
+| `()` | 每父节点唯一的命名子域 | `Catalogs`、`DescriptorContract`、`Instruction`、`CodeBinding` 等 |
+| `[]` | 直接、有序或可重复事实 | catalog 条目、mapping 条目、includes 等 |
+
+规则的重点是语义分配，不是把 XML tag/attribute 机械换一种括号。consumer 不得读取 parser-private 字段，也不得重建 `@_attribute` 一类 XML 对象形状。
+
+## 权威文档
+
+| 文档 | 回答的问题 |
+|---|---|
+| [language.md](language.md) | XNL 通道、身份、引用、声明式边界与 normalized projection。 |
+| [documents.md](documents.md) | package、catalog、KindDefinition、descriptor、mapping 各自长什么样。 |
+| [files.md](files.md) | 单文件/目录 bundle、`manifest.xnl`、logical path 与 provenance。 |
+| [projections.md](projections.md) | 单包 tree、ordered layers、tombstone、typed dependency 与 revision 的 authority 边界。 |
+| [skill-capsules.md](skill-capsules.md) | SkillCapsule version authority、sibling dependency、closure plan/apply 与 host 边界。 |
+| [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。
+
+多个 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)。
+
+本目录自身也是 `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。
+
+## 暂缓边界
+
+BusinessObject 与 PageObject 的通用外壳仍服从本目录的 `Tag/#id/metadata/{}/()/[]` 公理，但以下内容在当前版本中**刻意不定义**：
+
+- 专用字段与 operation/mutation/action 模型；
+- application assembly 的二者专用 public types；
+- 参考实现正在重构的 PageObject API 映射；
+- 二者最终 KindDefinition descriptor contract。
+
+这些内容由 mission `halfcode-compiler-xnl-migration` 的 `LATE-BO-PO` group 在重新观察参考实现后补充。