instant-ctrl-flow-logic 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instant-ctrl-flow-logic",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "description": "InstantCtrlFlow 引擎：xnl bundle 加载 → 行为树编译 → 无状态单次执行",
   "type": "module",

package/src/loader.ts

@@ -64,6 +64,9 @@ const PROFILE_STATEMENTS: Record<FlowForm, ReadonlySet<string>> = {
   BPCtrlFlow: new Set([...COMMON_STATEMENTS, 'ExternalJob', 'Timer', 'TaskStep']),
 };
 const CODE_REF = /^vfs:\/\/[^#\s]+#[A-Za-z_$][A-Za-z0-9_$]*$/;
+const HALF_CODE_RESOURCE_ENVELOPE_VERSION = 'halfcode.resource-envelope/v1';
+const DEPA_FLOW_SEMANTIC_API_VERSION = 'depa.flows/v1';
+const DEPA_FLOW_RESOURCE_SPEC_VERSION = 1;
 
 interface XnlEl {
   kind: string;
@@ -75,6 +78,64 @@ interface XnlEl {
   extend?: { order?: string[]; children: Record<string, XnlEl> };
 }
 
+interface FlowRootIdentityProjection {
+  apiVersion: string;
+  version: string;
+  diagnostic?: { code: string; message: string };
+}
+
+function projectFlowRootIdentity(metadata: Readonly<Record<string, unknown>>): FlowRootIdentityProjection {
+  const legacyApiVersion = typeof metadata.apiVersion === 'string' ? metadata.apiVersion : undefined;
+  const legacyVersion = typeof metadata.version === 'string' ? metadata.version : undefined;
+  const hasLegacyMetadata = metadata.apiVersion !== undefined || metadata.version !== undefined;
+  const hasResourceMetadata = metadata.envelopeVersion !== undefined || metadata.specVersion !== undefined;
+  if (hasLegacyMetadata && hasResourceMetadata) {
+    return {
+      apiVersion: '',
+      version: '',
+      diagnostic: {
+        code: 'mixed-flow-root-metadata',
+        message: 'flow root must use either depa apiVersion/version or Halfcode envelopeVersion/specVersion metadata',
+      },
+    };
+  }
+  if (hasResourceMetadata) {
+    if (metadata.envelopeVersion !== HALF_CODE_RESOURCE_ENVELOPE_VERSION) {
+      return {
+        apiVersion: '',
+        version: '',
+        diagnostic: {
+          code: 'unsupported-flow-resource-envelope',
+          message: `flow resource root requires envelopeVersion "${HALF_CODE_RESOURCE_ENVELOPE_VERSION}"`,
+        },
+      };
+    }
+    if (metadata.specVersion !== DEPA_FLOW_RESOURCE_SPEC_VERSION) {
+      return {
+        apiVersion: '',
+        version: '',
+        diagnostic: {
+          code: 'unsupported-flow-resource-spec-version',
+          message: `flow resource root requires numeric specVersion ${DEPA_FLOW_RESOURCE_SPEC_VERSION}`,
+        },
+      };
+    }
+    return {
+      apiVersion: DEPA_FLOW_SEMANTIC_API_VERSION,
+      version: String(DEPA_FLOW_RESOURCE_SPEC_VERSION),
+    };
+  }
+  if (legacyApiVersion && legacyVersion) return { apiVersion: legacyApiVersion, version: legacyVersion };
+  return {
+    apiVersion: legacyApiVersion ?? '',
+    version: legacyVersion ?? '',
+    diagnostic: {
+      code: 'container-missing-meta',
+      message: 'container missing metadata "apiVersion" or "version"',
+    },
+  };
+}
+
 const isEl = (n: unknown): n is XnlEl =>
   !!n && typeof n === 'object' && ((n as XnlEl).kind === 'DataElement' || (n as XnlEl).kind === 'TextElement');
 
@@ -428,11 +489,13 @@ function loadCtrlFlowSources(
     : undefined;
   const stateSeed = facets['state.seed'] ? { ...(facets['state.seed'].attributes ?? {}) } : undefined;
   const taskSpace = facets['task.space'] ? toNodeSpec(facets['task.space']) : undefined;
+  const rootIdentity = projectFlowRootIdentity(container.metadata ?? {});
+  if (rootIdentity.diagnostic) note(rootIdentity.diagnostic.code, rootIdentity.diagnostic.message);
   const spec: FlowBundleSpec = {
     form,
     fqn,
-    apiVersion: String(container.metadata?.apiVersion ?? ''),
-    version: String(container.metadata?.version ?? ''),
+    apiVersion: rootIdentity.apiVersion,
+    version: rootIdentity.version,
     title: container.attributes?.title as string | undefined,
     sourceNames,
     baseUri: options.baseUri,
@@ -447,7 +510,6 @@ function loadCtrlFlowSources(
     taskSpace,
     diagnostics,
   };
-  if (!spec.apiVersion) note('container-missing-meta', 'container missing metadata "apiVersion"');
   if (!fqn.includes('.')) note('container-id-not-fqn', `container #id must be a dotted FQN, got "${fqn}"`);
   return { spec, diagnostics };
 }