@neocompose/cli 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- Include relation-kind metadata when pushing internal record relations so
+  `@relations` changes pass server transaction admission.
+- Report the actual HTTP response status when a push is rejected.
+
 ## [0.6.5] - 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
       ),
       {
@@ -49561,15 +49791,6 @@ var init_doctor = __esm({
 });
 
 // ../src/database/project-version-intents.ts
-var project_version_intents_exports = {};
-__export(project_version_intents_exports, {
-  PROJECT_VERSION_INTENT_SCHEMA_VERSION: () => PROJECT_VERSION_INTENT_SCHEMA_VERSION,
-  ProjectVersionIntentType: () => ProjectVersionIntentType,
-  assertProjectVersionIntentIsKnown: () => assertProjectVersionIntentIsKnown,
-  assertProjectVersionIntentMatchesDiff: () => assertProjectVersionIntentMatchesDiff,
-  createProjectVersionIntent: () => createProjectVersionIntent,
-  isKnownProjectVersionIntentType: () => isKnownProjectVersionIntentType
-});
 function createProjectVersionIntent(type, details) {
   if (details === void 0) {
     return {
@@ -49588,24 +49809,6 @@ function isKnownProjectVersionIntentType(value) {
     value
   );
 }
-function assertProjectVersionIntentIsKnown(intent) {
-  if (!isKnownProjectVersionIntentType(intent.type)) {
-    throw new Error(`Unknown project version intent type "${intent.type}".`);
-  }
-  if (intent.schemaVersion !== PROJECT_VERSION_INTENT_SCHEMA_VERSION) {
-    throw new Error(
-      `Project version intent "${intent.type}" uses schema version ${intent.schemaVersion}; expected ${PROJECT_VERSION_INTENT_SCHEMA_VERSION}.`
-    );
-  }
-}
-function assertProjectVersionIntentMatchesDiff(args) {
-  assertProjectVersionIntentIsKnown(args.intent);
-  if (args.diff.set === void 0 && args.diff.unset === void 0) {
-    throw new Error(
-      `Project version intent "${args.intent.type}" cannot be recorded with an empty diff.`
-    );
-  }
-}
 var ProjectVersionIntentType, PROJECT_VERSION_INTENT_SCHEMA_VERSION;
 var init_project_version_intents = __esm({
   "../src/database/project-version-intents.ts"() {
@@ -62082,6 +62285,34 @@ var init_project_file_push = __esm({
   }
 });
 
+// src/commands/push-change-intent.ts
+function createNeoCliPushIntent(change) {
+  const intentType = `${change.recordKind}.${change.kind}`;
+  if (!isKnownProjectVersionIntentType(intentType)) {
+    throw new Error(`No project version intent exists for "${intentType}".`);
+  }
+  if (change.recordKind !== "internal-record-relation") {
+    return createProjectVersionIntent(intentType, { source: "neo-cli" });
+  }
+  const relationData = change.kind === "delete" ? change.baseData : change.nextData;
+  if (!isInternalRecordRelation(relationData)) {
+    throw new Error(
+      `Cannot push internal record relation "${change.recordId}": ${change.kind} change has invalid relation data.`
+    );
+  }
+  return createProjectVersionIntent(intentType, {
+    source: "neo-cli",
+    relationKind: relationData.relationKind
+  });
+}
+var init_push_change_intent = __esm({
+  "src/commands/push-change-intent.ts"() {
+    "use strict";
+    init_project_version_intents();
+    init_project2();
+  }
+});
+
 // src/commands/push.ts
 var push_exports = {};
 __export(push_exports, {
@@ -62736,22 +62967,13 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     {
       operation: transactionOperation,
       changes: status.changes.map((change) => {
-        const intentType = `${change.recordKind}.${change.kind}`;
-        if (!isKnownProjectVersionIntentType2(intentType)) {
-          throw new Error(
-            `No project version intent exists for "${intentType}".`
-          );
-        }
         return {
           recordKind: change.recordKind,
           recordId: change.recordId,
           operation: change.kind,
           nextData: change.kind === "delete" ? void 0 : stripServerDerivedNeoScript(change.nextData),
           deleted: change.kind === "delete" ? true : void 0,
-          intent: createProjectVersionIntent2(
-            intentType,
-            { source: "neo-cli" }
-          ),
+          intent: createNeoCliPushIntent(change),
           expectedBaseContentHash: change.kind === "create" ? null : change.casBaseHash ?? null
         };
       }),
@@ -62929,7 +63151,7 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
         } catch (retryError) {
           progress.stop();
           if (retryError instanceof NeoApiError) {
-            reportPushRejection(retryError.body);
+            reportPushRejection(retryError.status, retryError.body);
             process.exitCode = 1;
             return;
           }
@@ -62942,7 +63164,7 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
       process.exitCode = 1;
       return;
     }
-    reportPushRejection(rejection);
+    reportPushRejection(error.status, rejection);
     process.exitCode = 1;
     return;
   }
@@ -63064,7 +63286,7 @@ function stripServerDerivedNeoScript(value) {
   if (next.kind === 23) delete next.action;
   return next;
 }
-function reportPushRejection(body) {
+function reportPushRejection(status, body) {
   if (isObjectRecord2(body) && body.error === "base-hash-conflict") {
     console.error(
       'Push rejected: the server has newer state for these records. Run "neo pull" to merge, then push again.'
@@ -63091,7 +63313,7 @@ function reportPushRejection(body) {
     );
     return;
   }
-  console.error(`Push rejected (409): ${JSON.stringify(body)}`);
+  console.error(`Push rejected (${status}): ${JSON.stringify(body)}`);
 }
 function immediateTransactionId(result) {
   if (!isObjectRecord2(result)) return null;
@@ -64064,7 +64286,7 @@ function compileMigrationAction(schema, migrationData) {
     migrationContext: true
   });
 }
-var compileNSAction2, compileNSFunction2, compileNSGetter2, compileNSSetter2, createProjectVersionIntent2, isKnownProjectVersionIntentType2, ProjectTransactionInterruptedError, ProjectTransactionFailedError, PROJECT_TRANSACTION_POLL_DELAYS_MS;
+var compileNSAction2, compileNSFunction2, compileNSGetter2, compileNSSetter2, ProjectTransactionInterruptedError, ProjectTransactionFailedError, PROJECT_TRANSACTION_POLL_DELAYS_MS;
 var init_push = __esm({
   "src/commands/push.ts"() {
     "use strict";
@@ -64074,7 +64296,6 @@ var init_push = __esm({
     init_document();
     init_http();
     init_ui();
-    init_project_version_intents();
     init_workspace();
     init_project_documents();
     init_workspace_status();
@@ -64084,8 +64305,8 @@ var init_push = __esm({
     init_project_file_push();
     init_project_manifest();
     init_merge();
+    init_push_change_intent();
     ({ compileNSAction: compileNSAction2, compileNSFunction: compileNSFunction2, compileNSGetter: compileNSGetter2, compileNSSetter: compileNSSetter2 } = compiler_adapter_exports);
-    ({ createProjectVersionIntent: createProjectVersionIntent2, isKnownProjectVersionIntentType: isKnownProjectVersionIntentType2 } = project_version_intents_exports);
     ProjectTransactionInterruptedError = class extends Error {
       constructor(transactionId) {
         super(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.6.5",
+  "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: