@rsconcept/domain 2.3.0 → 3.0.1

package/src/library/oss-api.ts

@@ -7,9 +7,11 @@ import { type AliasMapping, applyAliasMapping, applyTypificationMapping, isSetTy
 import { labelType } from '../rslang/labels';
 import { extractBases } from '../rslang/semantic/typification-api';
 
+import { formatDependencyCycle } from './diagnostics';
 import { type LibraryItem } from './library';
 import { NodeType, type OperationSchema, type SubstitutionErrorDescription, SubstitutionErrorType } from './oss';
 import { type Constituenta, CstClass, CstType, type RSForm, type Substitution } from './rsform';
+import { type FormalOrderFields } from './rsform-api';
 
 const STARTING_SUB_INDEX = 900; // max semantic index for starting substitution
 
@@ -100,7 +102,10 @@ export class SubstitutionValidator {
     if (!this.checkTypes()) {
       return false;
     }
-    if (!this.checkCycles()) {
+    if (!this.checkTypificationCycles()) {
+      return false;
+    }
+    if (!this.checkDefinitionCycles()) {
       return false;
     }
     if (!this.checkSubstitutions()) {
@@ -237,7 +242,11 @@ export class SubstitutionValidator {
     return true;
   }
 
-  private checkCycles(): boolean {
+  /**
+   * Detect cycles among base/constant sets implied by typifications of non-base
+   * constituents under the substitution table.
+   */
+  private checkTypificationCycles(): boolean {
     const graph = new Graph();
     for (const schema of this.schemas) {
       for (const cst of schema.items) {
@@ -285,6 +294,64 @@ export class SubstitutionValidator {
     return true;
   }
 
+  /**
+   * Detect logical cycles in formal definitions after applying the substitution table
+   * (e.g. D16 := F2[D15] with identification D15 → D16 yields D16 := F2[D16]).
+   */
+  private checkDefinitionCycles(): boolean {
+    const graph = new Graph();
+    for (const schema of this.schemas) {
+      for (const [id, node] of schema.graph.nodes) {
+        graph.addNode(id);
+        for (const output of node.outputs) {
+          graph.addEdge(id, output);
+        }
+      }
+    }
+
+    const deleted = new Map<number, number>();
+    for (const item of this.substitutions) {
+      deleted.set(item.original, item.substitution);
+    }
+    const resolve = (id: number): number => deleted.get(id) ?? id;
+
+    const result = new Graph();
+    for (const id of graph.nodes.keys()) {
+      if (!deleted.has(id)) {
+        result.addNode(id);
+      }
+    }
+    for (const substitutionId of deleted.values()) {
+      result.addNode(substitutionId);
+    }
+
+    for (const [id, node] of graph.nodes) {
+      for (const output of node.outputs) {
+        if (deleted.has(output)) {
+          continue;
+        }
+        result.addEdge(resolve(id), output);
+      }
+    }
+
+    const cycle = result.findCycle();
+    if (cycle !== null) {
+      const aliases = cycle.map(id => {
+        const cst = this.cstByID.get(id);
+        if (!cst) {
+          return String(id);
+        }
+        if (this.schemas.length > 1) {
+          const schema = this.schemaByID.get(cst.schema);
+          return schema ? `[${schema.alias}]-${cst.alias}` : cst.alias;
+        }
+        return cst.alias;
+      });
+      return this.reportError(SubstitutionErrorType.definitionCycle, [formatDependencyCycle(aliases)]);
+    }
+    return true;
+  }
+
   private checkSubstitutions(): boolean {
     const baseMappings = this.prepareBaseMappings();
     const typeMappings = this.calculateSubstituteMappings(baseMappings);
@@ -387,7 +454,10 @@ export class SubstitutionValidator {
     return result;
   }
 
-  private checkEqual(left: Constituenta, right: Constituenta): boolean {
+  private checkEqual(
+    left: FormalOrderFields & { schema: number },
+    right: FormalOrderFields & { schema: number }
+  ): boolean {
     const schema1 = this.schemaByID.get(left.schema)!;
     const inputs1 = schema1.graph.at(left.id)!.inputs;
     if (inputs1.some(id => !this.constituents.has(id))) {
@@ -403,10 +473,10 @@ export class SubstitutionValidator {
     return expression1.replace(/\s+/g, '') === expression2.replace(/\s+/g, '');
   }
 
-  private reportError(errorType: SubstitutionErrorType, params: string[]): boolean {
+  private reportError(code: SubstitutionErrorType, params: string[]): boolean {
     this.errors.push({
-      errorType: errorType,
-      params: params
+      code,
+      params
     });
     return false;
   }

package/src/library/oss.ts

@@ -4,6 +4,7 @@
 
 import { type Graph } from '../graph';
 
+import { RSDiagnosticCode } from './diagnostics';
 import { type LibraryItem } from './library';
 import { type NodePosition, type OssLayout } from './oss-layout';
 
@@ -126,25 +127,30 @@ export interface OperationSchema extends LibraryItem {
   itemByNodeID: Map<string, OssItem>;
 }
 
-/** Represents substitution error description. */
+/** Represents substitution error description (same code space as {@link RSDiagnosticCode}). */
 export interface SubstitutionErrorDescription {
-  errorType: SubstitutionErrorType;
+  code: SubstitutionErrorType;
   params: string[];
 }
 
-/** Represents Substitution table error types. */
+/**
+ * Substitution-table error codes — aliases into {@link RSDiagnosticCode}.
+ * Logical definition cycles reuse {@link RSDiagnosticCode.schemaDependencyCycle}.
+ */
 export const SubstitutionErrorType = {
-  invalidIDs: 0,
-  incorrectCst: 1,
-  invalidClasses: 2,
-  invalidBasic: 3,
-  invalidConstant: 4,
-  typificationCycle: 5,
-  baseSubstitutionNotSet: 6,
-  unequalTypification: 7,
-  unequalExpressions: 8,
-  unequalArgsCount: 9,
-  unequalArgs: 10,
-  invalidNominal: 11
-} as const;
+  invalidIDs: RSDiagnosticCode.substitutionInvalidIDs,
+  incorrectCst: RSDiagnosticCode.substitutionIncorrectCst,
+  invalidClasses: RSDiagnosticCode.substitutionInvalidClasses,
+  invalidBasic: RSDiagnosticCode.substitutionInvalidBasic,
+  invalidConstant: RSDiagnosticCode.substitutionInvalidConstant,
+  typificationCycle: RSDiagnosticCode.substitutionTypificationCycle,
+  baseSubstitutionNotSet: RSDiagnosticCode.substitutionBaseNotSet,
+  unequalTypification: RSDiagnosticCode.substitutionUnequalTypification,
+  unequalExpressions: RSDiagnosticCode.substitutionUnequalExpressions,
+  unequalArgsCount: RSDiagnosticCode.substitutionUnequalArgsCount,
+  unequalArgs: RSDiagnosticCode.substitutionUnequalArgs,
+  invalidNominal: RSDiagnosticCode.substitutionInvalidNominal,
+  /** Same code as constituent schema dependency cycle. */
+  definitionCycle: RSDiagnosticCode.schemaDependencyCycle
+} as const satisfies Record<string, (typeof RSDiagnosticCode)[keyof typeof RSDiagnosticCode]>;
 export type SubstitutionErrorType = (typeof SubstitutionErrorType)[keyof typeof SubstitutionErrorType];

package/src/library/rsform-api/alias.ts

@@ -7,10 +7,10 @@ import { type AliasMapping, applyAliasMapping, applyTypificationMapping } from '
 import { type ArgumentValue, CstType, type RSForm } from '../rsform';
 
 import { getCstTypePrefix } from './cst-type';
-import { type AliasTypedConstituenta } from './types';
+import { type AliasTypedFields } from './types';
 
-/** Fields of {@link Constituenta} updated in place by alias mapping. */
-export interface ConstituentaMappableFields {
+/** Fields updated in place by alias mapping. */
+export interface MappableFields {
   alias: string;
   definition_formal: string;
   typification_manual: string;
@@ -77,7 +77,7 @@ export function generateAlias(type: CstType, schema: RSForm, takenAliases: strin
  * Remap formal expressions and terminological entity references in constituent fields.
  * Mutates each element of `items` in place; pass owned or cloned data only.
  */
-export function applyMappingToConstituents<T extends ConstituentaMappableFields>(
+export function applyMappingToConstituents<T extends MappableFields>(
   items: T[],
   mapping: AliasMapping,
   changeAliases: boolean
@@ -94,7 +94,7 @@ export function applyMappingToConstituents<T extends ConstituentaMappableFields>
 }
 
 /** Highest numeric alias suffix for {@link type} among {@link items} (0 when none). */
-export function maxAliasIndex(items: readonly AliasTypedConstituenta[], type: CstType): number {
+export function maxAliasIndex(items: readonly AliasTypedFields[], type: CstType): number {
   const prefix = getCstTypePrefix(type);
   return items.reduce((max, cst) => {
     if (cst.cst_type !== type) {
@@ -109,7 +109,7 @@ export function maxAliasIndex(items: readonly AliasTypedConstituenta[], type: Cs
  * Build alias → new-alias mapping that renumbers each type sequentially in list order.
  * Matches backend {@code RSFormCached.reset_aliases}.
  */
-export function buildSequentialAliasMapping(items: readonly AliasTypedConstituenta[]): AliasMapping {
+export function buildSequentialAliasMapping(items: readonly AliasTypedFields[]): AliasMapping {
   const counts: Record<string, number> = {};
   for (const value of Object.values(CstType)) {
     counts[value] = 1;
@@ -130,8 +130,8 @@ export function buildSequentialAliasMapping(items: readonly AliasTypedConstituen
  * Returns an empty mapping when the receiver has no items (aliases kept as-is).
  */
 export function allocateImportAliases(
-  receiver: readonly AliasTypedConstituenta[],
-  source: readonly AliasTypedConstituenta[]
+  receiver: readonly AliasTypedFields[],
+  source: readonly AliasTypedFields[]
 ): AliasMapping {
   if (receiver.length === 0) {
     return {};

package/src/library/rsform-api/cst-type.ts

@@ -4,7 +4,9 @@
 
 import { TypeClass, TypeID, type Typification } from '../../rslang';
 import { type EchelonFunctional, isTypification } from '../../rslang/semantic/typification';
-import { type Constituenta, CstClass, CstType } from '../rsform';
+import { CstClass, CstType } from '../rsform';
+
+import { type StructureCapableFields } from './types';
 
 /** Record of {@link CstType} prefixes. */
 const CST_TYPE_PREFIX: Record<CstType, string> = {
@@ -58,8 +60,8 @@ export function inferClass(type: CstType, isTemplate: boolean = false): CstClass
   return CST_TYPE_TO_CLASS[type];
 }
 
-/** Check if {@link Constituenta} is a template or a category. */
-export function isTemplateCst(cst: Constituenta): boolean {
+/** Check if item type is a template or a category. */
+export function isTemplateCst(cst: { cst_type: CstType }): boolean {
   return cst.cst_type === CstType.FUNCTION || cst.cst_type === CstType.PREDICATE || cst.cst_type === CstType.STATEMENT;
 }
 
@@ -177,8 +179,8 @@ export function typeClassForCstType(cstType: CstType): TypeClass {
   }
 }
 
-/** Evaluate if {@link Constituenta} can be used produce structure. */
-export function canProduceStructure(cst: Constituenta): boolean {
+/** Evaluate if an item can be used to produce structure. */
+export function canProduceStructure(cst: StructureCapableFields): boolean {
   switch (cst.cst_type) {
     case CstType.NOMINAL:
     case CstType.BASE:

package/src/library/rsform-api/expression.ts

@@ -5,7 +5,7 @@
 import { type AstNode } from '../../parsing';
 import { ValueClass } from '../../rslang';
 import { generateExpressionFromAst, parseRSLangExpression } from '../../rslang/api';
-import { type ArgumentValue, type Constituenta, CstStatus, CstType } from '../rsform';
+import { type ArgumentValue, CstStatus, CstType } from '../rsform';
 
 import { isBasicConcept } from './cst-type';
 
@@ -61,8 +61,8 @@ export function inferTemplate(expression: string): boolean {
   return (match && match?.length > 0) ?? false;
 }
 
-/** Apply filter based on start {@link Constituenta} type. */
-export function applyFilterCategory(start: Constituenta, items: Constituenta[]): Constituenta[] {
+/** Apply filter based on start item type within an ordered list. */
+export function applyFilterCategory<T extends { cst_type: CstType }>(start: T, items: readonly T[]): T[] {
   const startIndex = items.indexOf(start);
   if (startIndex === -1) {
     return [];

package/src/library/rsform-api/formal-graph.test.ts

@@ -4,9 +4,9 @@ import { CstType } from '../rsform';
 
 import { buildFormalDependencyGraph, restoreConstituentOrder } from './formal-graph';
 import { computeSemanticRelations } from './semantic-relations';
-import { type OrderableConstituenta } from './types';
+import { type FormalOrderFields } from './types';
 
-function cst(id: number, alias: string, cst_type: CstType, definition_formal = ''): OrderableConstituenta {
+function cst(id: number, alias: string, cst_type: CstType, definition_formal = ''): FormalOrderFields {
   return { id, alias, cst_type, definition_formal };
 }
 

package/src/library/rsform-api/formal-graph.ts

@@ -7,13 +7,13 @@ import { extractGlobals } from '../../rslang/api';
 import { CstType } from '../rsform';
 
 import { computeSemanticRelations } from './semantic-relations';
-import { type OrderableConstituenta, type SemanticRelations } from './types';
+import { type FormalOrderFields, type SemanticRelations } from './types';
 
 /**
  * Build the formal dependency graph: supplier → dependent.
  * Matches backend {@code RSForm.graph_formal}.
  */
-export function buildFormalDependencyGraph(items: readonly OrderableConstituenta[]): Graph<number> {
+export function buildFormalDependencyGraph(items: readonly FormalOrderFields[]): Graph<number> {
   const graph = new Graph<number>();
   const byAlias = new Map(items.map(cst => [cst.alias, cst]));
   for (const cst of items) {
@@ -36,7 +36,7 @@ export function buildFormalDependencyGraph(items: readonly OrderableConstituenta
  *
  * One Kahn pass over the formal dependency graph.
  */
-export function restoreConstituentOrder<T extends OrderableConstituenta>(
+export function restoreConstituentOrder<T extends FormalOrderFields>(
   items: readonly T[],
   graph: Graph<number> = buildFormalDependencyGraph(items),
   relations: SemanticRelations = computeSemanticRelations(items, graph)
@@ -77,9 +77,7 @@ export function restoreConstituentOrder<T extends OrderableConstituenta>(
   const pendingChildren: number[] = [];
 
   function enqueueSticky(candidateIds: readonly number[]): void {
-    const sticky = candidateIds.filter(
-      childId => ready.has(childId) && !pendingChildren.includes(childId)
-    );
+    const sticky = candidateIds.filter(childId => ready.has(childId) && !pendingChildren.includes(childId));
     sticky.sort((left, right) => (rank.get(left) ?? 0) - (rank.get(right) ?? 0));
     pendingChildren.push(...sticky);
   }
@@ -138,7 +136,7 @@ export function restoreConstituentOrder<T extends OrderableConstituenta>(
   return result;
 }
 
-function kernelPriority<T extends OrderableConstituenta>(
+function kernelPriority<T extends FormalOrderFields>(
   items: readonly T[],
   graph: Graph<number>,
   parentOf: Map<number, number>
@@ -176,9 +174,7 @@ function kernelPriority<T extends OrderableConstituenta>(
       const parentId = parentOf.get(cst.id) ?? cst.id;
       const parent = byId.get(parentId);
       return (
-        cst.cst_type === CstType.STRUCTURED ||
-        cst.cst_type === CstType.AXIOM ||
-        parent?.cst_type === CstType.STRUCTURED
+        cst.cst_type === CstType.STRUCTURED || cst.cst_type === CstType.AXIOM || parent?.cst_type === CstType.STRUCTURED
       );
     })
     .map(cst => cst.id);

package/src/library/rsform-api/index.ts

@@ -8,8 +8,8 @@ export {
   applyMappingToConstituents,
   argumentValuesToMapping,
   buildSequentialAliasMapping,
-  type ConstituentaMappableFields,
   generateAlias,
+  type MappableFields,
   maxAliasIndex,
   removeAliasReference,
   validateAliasFormat,
@@ -40,7 +40,7 @@ export {
   type InlineSynthesisInput,
   type InlineSynthesisResult,
   sortItemsForInlineSynthesis,
-  type SynthesizableConstituenta
+  type SynthesizableFields
 } from './synthesis';
 export {
   buildDefinitionReferenceGraph,
@@ -50,4 +50,19 @@ export {
   type TextChangeOptions
 } from './text-resolution';
 export { insertItemAfter, moveIdsInOrder, reorderItemsByIds } from './transforms';
-export type { AliasTypedConstituenta, OrderableConstituenta, ResolvableConstituenta, SemanticRelations } from './types';
+export type {
+  AliasTypedFields,
+  BasicTextCheckFields,
+  DescribableFields,
+  DiagnosticSourceFields,
+  FormalOrderFields,
+  ModelEvalFields,
+  SchemaIssueFields,
+  SearchableFields,
+  SemanticRelations,
+  SpawnPathFields,
+  StructureCapableFields,
+  TemplateParamSourceFields,
+  TemplateSourceFields,
+  TextResolvableFields
+} from './types';

package/src/library/rsform-api/semantic-relations.ts

@@ -8,16 +8,13 @@ import { CstType } from '../rsform';
 
 import { isBaseSet, isFunctional } from './cst-type';
 import { inferTemplate } from './expression';
-import { type OrderableConstituenta, type SemanticRelations } from './types';
+import { type FormalOrderFields, type SemanticRelations } from './types';
 
 /**
  * Infer semantic parent/children used for clustering during restore order.
  * Port of backend {@code SemanticInfo}.
  */
-export function computeSemanticRelations(
-  items: readonly OrderableConstituenta[],
-  graph: Graph<number>
-): SemanticRelations {
+export function computeSemanticRelations(items: readonly FormalOrderFields[], graph: Graph<number>): SemanticRelations {
   const byId = new Map(items.map(cst => [cst.id, cst]));
   const byAlias = new Map(items.map(cst => [cst.alias, cst]));
   const isTemplate = new Map<number, boolean>();
@@ -41,7 +38,7 @@ export function computeSemanticRelations(
     return !isFunctional(base.cst_type) || splitTemplateDefinition(base.definition_formal).head !== head;
   }
 
-  function extractSources(target: OrderableConstituenta): Set<number> {
+  function extractSources(target: FormalOrderFields): Set<number> {
     const sources = new Set<number>();
     if (!isFunctional(target.cst_type)) {
       for (const parentId of graph.at(target.id)?.inputs ?? []) {
@@ -76,7 +73,7 @@ export function computeSemanticRelations(
     return sources;
   }
 
-  function inferSimple(target: OrderableConstituenta): boolean {
+  function inferSimple(target: FormalOrderFields): boolean {
     if (target.cst_type === CstType.STRUCTURED || isBaseSet(target.cst_type)) {
       return false;
     }

package/src/library/rsform-api/stats.ts

@@ -4,12 +4,13 @@
 
 import { TypeID, type Typification, ValueClass } from '../../rslang';
 import { hasCstDiagnostic, RSDiagnosticCode } from '../diagnostics';
-import { type Constituenta, CstStatus, CstType, type RSForm, type RSFormStats } from '../rsform';
+import { CstStatus, CstType, type RSForm, type RSFormStats } from '../rsform';
 
 import { isBasicConcept, isLogical } from './cst-type';
+import { type BasicTextCheckFields, type SchemaIssueFields, type StructureCapableFields } from './types';
 
-/** Checks if {@link Constituenta} is a schema issue. */
-export function isSchemaIssue(cst: Constituenta): boolean {
+/** Checks if an item is a schema issue. */
+export function isSchemaIssue(cst: SchemaIssueFields): boolean {
   return (
     (cst.diagnostics?.length ?? 0) > 0 || cst.status === CstStatus.INCORRECT || cst.status === CstStatus.INCALCULABLE
   );
@@ -125,7 +126,7 @@ export function calculateSchemaStats(target: RSForm): RSFormStats {
   return stats;
 }
 
-function calculateStepComplexity(cst: Constituenta): number {
+function calculateStepComplexity(cst: StructureCapableFields): number {
   if (cst.cst_type === CstType.AXIOM || cst.cst_type === CstType.NOMINAL || !isBasicConcept(cst.cst_type)) {
     return 0;
   }
@@ -162,7 +163,7 @@ function calculateTypificationComplexity(type: Typification): number {
 }
 
 /** Non-logical basic concept missing convention and/or resolved term (trimmed). */
-function isMissingBasicText(cst: Constituenta): boolean {
+function isMissingBasicText(cst: BasicTextCheckFields): boolean {
   if (!isBasicConcept(cst.cst_type) || isLogical(cst.cst_type)) {
     return false;
   }

package/src/library/rsform-api/structure.ts

@@ -7,6 +7,8 @@ import { isTypification } from '../../rslang/semantic/typification';
 import { applyPath } from '../../rslang/semantic/typification-api';
 import { type Constituenta, type RSForm } from '../rsform';
 
+import { type SpawnPathFields, type StructureCapableFields } from './types';
+
 /**
  * Id to pass as `insert_after` when creating a new {@link Constituenta} spawned by `targetId`:
  * after the last existing child of that spawner, or after the spawner itself if none.
@@ -21,8 +23,8 @@ export function inferNewSpawnPosition(schema: RSForm, targetId: number): number
   return last ?? targetId;
 }
 
-/** Finds {@link Constituenta} by structure path. */
-export function findCstByStructure(schema: RSForm, target: Constituenta, path: TypePath): Constituenta | null {
+/** Finds schema item by absolute structure path under `targetId`. */
+export function findCstByStructure(schema: RSForm, target: { id: number }, path: TypePath): Constituenta | null {
   const byId = schema.cstByID ?? new Map(schema.items.map(item => [item.id, item]));
   for (const cst of schema.items) {
     if (!cst.spawner_path) {
@@ -36,8 +38,12 @@ export function findCstByStructure(schema: RSForm, target: Constituenta, path: T
   return null;
 }
 
-/** Retrieves name for piece of target {@link Constituenta} structure. */
-export function getStructureName(schema: RSForm, target: Constituenta, path: TypePath): string {
+/** Retrieves name for piece of target structure. */
+export function getStructureName(
+  schema: RSForm,
+  target: StructureCapableFields & { id: number },
+  path: TypePath
+): string {
   const representation = findCstByStructure(schema, target, path);
   if (representation) {
     return `${representation.alias}: ${representation.term_resolved}`;
@@ -56,9 +62,9 @@ export function getStructureName(schema: RSForm, target: Constituenta, path: Typ
 }
 
 function resolveAbsoluteSpawnerPath(
-  cst: Constituenta,
+  cst: SpawnPathFields,
   targetId: number,
-  byId: Map<number, Constituenta>
+  byId: Map<number, SpawnPathFields>
 ): TypePath | null {
   if (!cst.spawner_path || cst.spawner == null) {
     return null;

package/src/library/rsform-api/substitution.ts

@@ -5,7 +5,7 @@
 import { type AliasMapping } from '../../rslang/api';
 import { type Attribution, type Substitution } from '../rsform';
 
-import { applyMappingToConstituents, type ConstituentaMappableFields } from './alias';
+import { applyMappingToConstituents, type MappableFields } from './alias';
 import { remapAttributionsUnderSubstitution } from './attribution';
 
 /** Result of applying substitutions to a schema fragment. */
@@ -21,7 +21,7 @@ export interface SubstitutionResult<T> {
  * Apply constituenta substitutions: remap attributions, drop originals, rewrite aliases in survivors.
  * Does not resolve texts — call {@link resolveAllConstituentTexts} afterwards.
  */
-export function applyConstituentSubstitutions<T extends ConstituentaMappableFields & { id: number; alias: string }>(
+export function applyConstituentSubstitutions<T extends MappableFields & { id: number; alias: string }>(
   items: readonly T[],
   attributions: readonly Attribution[],
   substitutions: readonly Substitution[]

package/src/library/rsform-api/synthesis.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, it } from 'vitest';
 
-import { CstType } from '../rsform';
+import { LibraryItemType } from '../library';
+import { CstType, type RSForm } from '../rsform';
 
-import { inlineSynthesis } from './synthesis';
+import { inlineSynthesis, sortItemsForInlineSynthesis } from './synthesis';
 
 function item(partial: {
   id: number;
@@ -124,3 +125,33 @@ describe('inlineSynthesis', () => {
     expect(result.items).not.toBe(receiver);
   });
 });
+
+describe('sortItemsForInlineSynthesis', () => {
+  function libraryItem(partial: { id: number; location: string; owner: number | null; visible: boolean }) {
+    return {
+      id: partial.id,
+      item_type: LibraryItemType.RSFORM,
+      alias: `S${partial.id}`,
+      title: `Item ${partial.id}`,
+      description: '',
+      visible: partial.visible,
+      read_only: false,
+      location: partial.location,
+      access_policy: 'public' as const,
+      time_create: '',
+      time_update: '',
+      owner: partial.owner
+    };
+  }
+
+  it('orders by location, then owner+visible, then visible, then rest', () => {
+    const receiver = { location: '/a', owner: 1 } as RSForm;
+    const sameLocation = libraryItem({ id: 1, location: '/a', owner: 99, visible: false });
+    const sameOwnerVisible = libraryItem({ id: 2, location: '/b', owner: 1, visible: true });
+    const otherVisible = libraryItem({ id: 3, location: '/c', owner: 2, visible: true });
+    const hidden = libraryItem({ id: 4, location: '/d', owner: 2, visible: false });
+
+    const sorted = sortItemsForInlineSynthesis(receiver, [hidden, otherVisible, sameOwnerVisible, sameLocation]);
+    expect(sorted.map(item => item.id)).toEqual([1, 2, 3, 4]);
+  });
+});

package/src/library/rsform-api/synthesis.ts

@@ -10,23 +10,23 @@ import { type AliasMapping } from '../../rslang/api';
 import { type LibraryItem } from '../library';
 import { type Attribution, type CstType, type RSForm, type Substitution } from '../rsform';
 
-import { allocateImportAliases, applyMappingToConstituents, type ConstituentaMappableFields } from './alias';
+import { allocateImportAliases, applyMappingToConstituents, type MappableFields } from './alias';
 import { importAttributions } from './attribution';
 import { applyConstituentSubstitutions, remapSubstitutionsAfterImport } from './substitution';
 import { resolveAllConstituentTexts } from './text-resolution';
-import { type AliasTypedConstituenta, type ResolvableConstituenta } from './types';
+import { type AliasTypedFields, type TextResolvableFields } from './types';
 
-/** Constituent shape required for embedding / synthesis transforms. */
-export type SynthesizableConstituenta = ConstituentaMappableFields &
-  ResolvableConstituenta &
-  AliasTypedConstituenta & {
+/** Field intersection required for embedding / synthesis transforms. */
+export type SynthesizableFields = MappableFields &
+  TextResolvableFields &
+  AliasTypedFields & {
     id: number;
     alias: string;
     cst_type: CstType;
   };
 
 /** Input for {@link inlineSynthesis}. */
-export interface InlineSynthesisInput<T extends SynthesizableConstituenta> {
+export interface InlineSynthesisInput<T extends SynthesizableFields> {
   /** Receiver schema constituents (order preserved; imports append). */
   receiverItems: readonly T[];
   /** Receiver attributions (default empty). */
@@ -49,7 +49,7 @@ export interface InlineSynthesisInput<T extends SynthesizableConstituenta> {
 }
 
 /** Result of {@link inlineSynthesis}. */
-export interface InlineSynthesisResult<T extends SynthesizableConstituenta> {
+export interface InlineSynthesisResult<T extends SynthesizableFields> {
   items: T[];
   attributions: Attribution[];
   /** Updated next-id after inserts. */
@@ -71,7 +71,7 @@ export interface InlineSynthesisResult<T extends SynthesizableConstituenta> {
  * Resolves term/definition entity references on the result.
  * Does not mutate inputs.
  */
-export function inlineSynthesis<T extends SynthesizableConstituenta>(
+export function inlineSynthesis<T extends SynthesizableFields>(
   input: InlineSynthesisInput<T>
 ): InlineSynthesisResult<T> {
   const sourceItems = input.sourceItems;
@@ -147,19 +147,23 @@ export function inlineSynthesis<T extends SynthesizableConstituenta>(
 /** Sorts library items relevant for schema embedding with specified {@link RSForm}. */
 export function sortItemsForInlineSynthesis(receiver: RSForm, items: readonly LibraryItem[]): LibraryItem[] {
   const result = items.filter(item => item.location === receiver.location);
+  const included = new Set(result);
   for (const item of items) {
-    if (item.visible && item.owner === receiver.owner && !result.includes(item)) {
+    if (item.visible && item.owner === receiver.owner && !included.has(item)) {
       result.push(item);
+      included.add(item);
     }
   }
   for (const item of items) {
-    if (item.visible && !result.includes(item)) {
+    if (item.visible && !included.has(item)) {
       result.push(item);
+      included.add(item);
     }
   }
   for (const item of items) {
-    if (!result.includes(item)) {
+    if (!included.has(item)) {
       result.push(item);
+      included.add(item);
     }
   }
   return result;