@neocompose/cli 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [Unreleased]
+
+### Changed
+
+- Document the final relation-only world layer-link contract and keep the
+  format-4 Hello World corpus free of the retired value-side binding field.
+
+## [0.6.7] - 2026-07-21
+
+### Fixed
+
+- Treat class-level layer-link relations, including inherited targets, as the
+  authoritative binding during pull, status, diff, and push.
+- Reject concrete system layer-link bases, targetless concrete descendants,
+  ambiguous or invalid targets, abstract construction, and authored
+  `layerClassId` sidecars before a source transaction reaches the server.
+
 ## [0.6.6] - 2026-07-21
 
 ### Fixed

package/dist/neo.mjs

@@ -13981,6 +13981,7 @@ function validateProjectSourceSemantics(documents) {
       );
     }
   }
+  validateWorldLayerLinkSourceContracts(documents, environment, diagnostics);
   return diagnostics;
 }
 function contextualAnnotationFields(document, position) {
@@ -14500,6 +14501,188 @@ function relationFields(context, environment) {
   }
   return [];
 }
+function validateWorldLayerLinkSourceContracts(documents, environment, diagnostics) {
+  for (const [uri, document] of documents) {
+    for (const declaration of document.declarations) {
+      if (declaration.kind !== "class") continue;
+      const descriptor = worldLayerLinkSourceDescriptor(
+        declaration,
+        environment
+      );
+      if (descriptor === null) continue;
+      const directTargets = directLayerLinkTargets(declaration, uri);
+      const systemWorldKind = contextualAnnotationEnum(
+        declaration.annotations,
+        "system",
+        "worldKind"
+      );
+      const isSystemBase = systemWorldKind === descriptor.linkWorldKind;
+      if (isSystemBase) {
+        if (!declaration.modifiers.includes("abstract")) {
+          pushDiagnostic(
+            diagnostics,
+            uri,
+            declaration.nameRange,
+            "concrete-system-layer-link-base",
+            `System layer-link base '${declaration.name}' must be abstract.`
+          );
+        }
+        if (directTargets.length > 0) {
+          pushDiagnostic(
+            diagnostics,
+            uri,
+            directTargets[0].range,
+            "system-layer-link-target-relation",
+            `System layer-link base '${declaration.name}' cannot declare targetLayer. Declare the relation on a project-authored descendant instead.`
+          );
+        }
+      }
+      for (const target of directTargets) {
+        validateLayerLinkTargetSource(
+          declaration,
+          descriptor,
+          target,
+          environment,
+          diagnostics
+        );
+      }
+      if (isSystemBase || declaration.modifiers.includes("abstract")) continue;
+      const effectiveTargets = effectiveLayerLinkTargets(
+        declaration,
+        uri,
+        environment
+      );
+      if (effectiveTargets.length === 0) {
+        pushDiagnostic(
+          diagnostics,
+          uri,
+          declaration.nameRange,
+          "concrete-layer-link-missing-target",
+          `Concrete layer-link class '${declaration.name}' must resolve exactly one inherited or directly declared targetLayer relation.`
+        );
+      } else if (effectiveTargets.length > 1) {
+        pushDiagnostic(
+          diagnostics,
+          uri,
+          declaration.nameRange,
+          "concrete-layer-link-multiple-targets",
+          `Concrete layer-link class '${declaration.name}' resolves ${effectiveTargets.length} targetLayer relations at the nearest declaration depth; exactly one is required.`
+        );
+      }
+    }
+  }
+}
+function worldLayerLinkSourceDescriptor(declaration, environment) {
+  const worldKind = effectiveWorldKind(declaration, environment);
+  if (worldKind === "TileLayerLink") {
+    return {
+      linkWorldKind: "TileLayerLink",
+      targetWorldKind: "TileLayer"
+    };
+  }
+  if (worldKind === "ObjectLayerLink") {
+    return {
+      linkWorldKind: "ObjectLayerLink",
+      targetWorldKind: "ObjectLayer"
+    };
+  }
+  return null;
+}
+function directLayerLinkTargets(declaration, uri) {
+  const result = [];
+  for (const annotation2 of declaration.annotations) {
+    if (annotation2.name !== "relations") continue;
+    for (const argument2 of annotation2.arguments) {
+      if (argument2.name !== "targetLayer") continue;
+      let expression;
+      try {
+        expression = parseExpression(argument2.text);
+      } catch (error) {
+        if (error instanceof CompileError) continue;
+        throw error;
+      }
+      const entries = expression.kind === "litList" ? expression.elements : [expression];
+      for (const entry of entries) {
+        result.push({
+          expression: unwrapAnnotatedExpression(entry),
+          range: argument2.range,
+          uri
+        });
+      }
+    }
+  }
+  return result;
+}
+function effectiveLayerLinkTargets(declaration, uri, environment) {
+  const visited = /* @__PURE__ */ new Set();
+  let current = declaration;
+  let currentUri = uri;
+  while (current !== void 0 && !visited.has(current.name)) {
+    visited.add(current.name);
+    const systemWorldKind = contextualAnnotationEnum(
+      current.annotations,
+      "system",
+      "worldKind"
+    );
+    if (systemWorldKind === "TileLayerLink" || systemWorldKind === "ObjectLayerLink") {
+      return [];
+    }
+    const direct = directLayerLinkTargets(current, currentUri);
+    if (direct.length > 0) return direct;
+    const parent = current.baseTypes.map((base) => environment.types.get(base.name)).find((candidate) => candidate !== void 0);
+    current = parent;
+    currentUri = uri;
+  }
+  return [];
+}
+function validateLayerLinkTargetSource(declaration, descriptor, targetSource, environment, diagnostics) {
+  const expression = targetSource.expression;
+  if (isReferenceCall(expression)) return;
+  if (expression.kind !== "ident") {
+    pushDiagnostic(
+      diagnostics,
+      targetSource.uri,
+      targetSource.range,
+      "invalid-layer-link-target",
+      `Layer-link class '${declaration.name}' targetLayer must be a layer class symbol or typed Reference.`
+    );
+    return;
+  }
+  const target = environment.types.get(expression.name);
+  if (target === void 0) {
+    pushDiagnostic(
+      diagnostics,
+      targetSource.uri,
+      targetSource.range,
+      "unknown-layer-link-target",
+      `Layer-link class '${declaration.name}' targets unknown class '${expression.name}'.`
+    );
+    return;
+  }
+  const targetWorldKind = effectiveWorldKind(target, environment);
+  if (targetWorldKind !== descriptor.targetWorldKind) {
+    pushDiagnostic(
+      diagnostics,
+      targetSource.uri,
+      targetSource.range,
+      "wrong-layer-link-target-kind",
+      `Layer-link class '${declaration.name}' targetLayer '${target.name}' must extend world class kind '${descriptor.targetWorldKind}'.`
+    );
+    return;
+  }
+  if (target.modifiers.includes("abstract")) {
+    pushDiagnostic(
+      diagnostics,
+      targetSource.uri,
+      targetSource.range,
+      "abstract-layer-link-target",
+      `Layer-link class '${declaration.name}' targetLayer '${target.name}' must be concrete.`
+    );
+  }
+}
+function unwrapAnnotatedExpression(expression) {
+  return expression.kind === "annotated" ? unwrapAnnotatedExpression(expression.expression) : expression;
+}
 function effectiveWorldKind(declaration, environment) {
   const queue = [declaration];
   const seen = /* @__PURE__ */ new Set();
@@ -14829,7 +15012,26 @@ function validateExpression(expression, expected, scope, environment, uri, range
   if (expression.kind === "new") {
     const typeName = expression.className ?? expected?.name;
     const declaration = typeName ? environment.types.get(typeName) : void 0;
+    for (const entry of expression.initializer ?? []) {
+      if (entry.name !== "layerClassId") continue;
+      pushDiagnostic(
+        diagnostics,
+        uri,
+        range2,
+        "reserved-layer-class-id-source",
+        "layerClassId is an unsupported legacy field. Declare @relations(targetLayer: ...) on the concrete layer-link class instead."
+      );
+    }
     if (!declaration) return;
+    if (declaration.modifiers.includes("abstract")) {
+      pushDiagnostic(
+        diagnostics,
+        uri,
+        range2,
+        "abstract-class-instantiation",
+        `Cannot instantiate abstract class '${declaration.name}'. Use a concrete descendant instead.`
+      );
+    }
     const fields = declaration?.members.filter(
       (member) => member.kind === "field" && !member.modifiers.includes("static")
     ) ?? [];
@@ -14847,8 +15049,10 @@ function validateExpression(expression, expected, scope, environment, uri, range
       );
     });
     for (const entry of expression.initializer ?? []) {
-      const field = declaration?.members.find(
-        (candidate) => candidate.name === entry.name
+      const field = sourceClassFieldByName(
+        declaration,
+        entry.name,
+        environment
       );
       validateExpression(
         entry.value,
@@ -14950,6 +15154,19 @@ function validateExpression(expression, expected, scope, environment, uri, range
     );
   }
 }
+function sourceClassFieldByName(declaration, name, environment) {
+  const visited = /* @__PURE__ */ new Set();
+  let current = declaration;
+  while (current !== void 0 && !visited.has(current.name)) {
+    visited.add(current.name);
+    const member = current.members.find(
+      (candidate) => candidate.kind === "field" && candidate.name === name
+    );
+    if (member !== void 0) return member;
+    current = current.baseTypes.map((base) => environment.types.get(base.name)).find((candidate) => candidate !== void 0);
+  }
+  return void 0;
+}
 function semanticTypesAssignable(actual, expected) {
   if (actual.name === expected.name) return true;
   if (actual.name === "int" && (expected.name === "float" || expected.name === "decimal")) {
@@ -40331,6 +40548,11 @@ function lowerSeedRow(context, member, sourceExpression, source, valueId, path,
     if (effectiveClass === void 0) {
       throw new Error(`Unknown value class ${member.classId}.`);
     }
+    if (effectiveClass.declarationModifier === "abstract") {
+      throw new Error(
+        `Cannot instantiate abstract class ${effectiveClass.name} for ${path}. Use a concrete descendant instead.`
+      );
+    }
     classId = effectiveClass.id;
     const body = {};
     for (const assignment of expression.initializer ?? []) {
@@ -40528,6 +40750,11 @@ function lowerClassValue(context, member, expression, base, source) {
   const schemaClass2 = context.classes.get(classId);
   if (schemaClass2 === void 0)
     throw new Error(`Unknown value class ${classId}.`);
+  if (schemaClass2.declarationModifier === "abstract") {
+    throw new Error(
+      `Cannot instantiate abstract class ${schemaClass2.name} for value ${String(base.id)}. Use a concrete descendant instead.`
+    );
+  }
   const baseBody = isObjectRecord2(base.value) ? base.value : {};
   const body = { ...baseBody };
   for (const assignment of expression.initializer ?? []) {
@@ -41368,7 +41595,7 @@ function classValue(context, member, value, visited, targetTyped) {
     return targetTyped ? "new()" : `new ${name}()`;
   const schema = isObjectRecord2(schemaClass2.schema) ? schemaClass2.schema : {};
   const order = Array.isArray(schemaClass2.schemaKeyOrder) ? schemaClass2.schemaKeyOrder.filter(
-    (entry) => typeof entry === "string"
+    (entry) => typeof entry === "string" && typeof schema[entry] === "string"
   ) : Object.keys(schema);
   const fields = [];
   for (const key of [
@@ -44914,7 +45141,7 @@ var init_project_migration_types = __esm({
 });
 
 // ../src/models/project/internal-record-relations.ts
-function worldClassContract(relationKind, sourceWorldKind, targetWorldKind, targetClassPolicy, merge, allowAbstractTarget) {
+function worldClassContract(relationKind, sourceWorldKind, targetWorldKind, targetClassPolicy, merge, allowAbstractTarget, allowDirectSystemSource = true) {
   return {
     relationKind,
     endpointPairs: [{ sourceRecordKind: "class", targetRecordKind: "class" }],
@@ -44924,6 +45151,7 @@ function worldClassContract(relationKind, sourceWorldKind, targetWorldKind, targ
     allowCycles: false,
     sourceWorldKind,
     targetWorldKind,
+    allowDirectSystemSource,
     allowAbstractTarget
   };
 }
@@ -45018,6 +45246,7 @@ var init_internal_record_relations = __esm({
         NeoWorldSystemClassKind.TileLayer,
         "exact",
         "nearest-single",
+        false,
         false
       ),
       worldClassContract(
@@ -45026,6 +45255,7 @@ var init_internal_record_relations = __esm({
         NeoWorldSystemClassKind.ObjectLayer,
         "exact",
         "nearest-single",
+        false,
         false
       ),
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -205,6 +205,14 @@ declarations. Structurally owned descriptors and concrete generic bindings
 derive their identities from stable owner roles; do not invent `@id`
 annotations for them.
 
+For world layer links, `NeoTileLayerLink` and `NeoObjectLayerLink` are abstract,
+relation-free system bases. Instantiate a concrete project-authored descendant
+that resolves exactly one `targetLayer` relation, declared directly or inherited
+from a project-authored ancestor. The class relation is the complete binding:
+native source emits no value-level target metadata, and link values carry no
+second persistence representation. Painting and other world-content writes
+never create or repair link targets.
+
 ## Root and authored values
 
 `Root.neo` contains a compiler-owned envelope of this form: