@rsconcept/domain 2.2.0 → 3.0.0

package/src/library/rsform-api/text-resolution.ts

@@ -0,0 +1,152 @@
+/**
+ * Cascade resolution of constituenta term/definition entity references.
+ * Matches backend {@code RSForm.resolve_all_text} / {@code resolve_term_change}.
+ */
+
+import { type TermContext } from '../../cctext/language';
+import { extractEntities, parseGrammemes, resolveTextReferences } from '../../cctext/language-api';
+import { Graph } from '../../graph';
+
+import { type TextResolvableFields } from './types';
+
+/** Options controlling which texts to re-resolve after an edit. */
+export interface TextChangeOptions {
+  termChanged: boolean;
+  termRawChanged: boolean;
+  definitionRawChanged: boolean;
+  clearTargetForms: boolean;
+}
+
+/** Build term-reference graph: referenced constituent → dependent (backend {@code graph_term}). */
+export function buildTermReferenceGraph(items: readonly TextResolvableFields[]): Graph<number> {
+  return buildReferenceGraph(items, 'term_raw');
+}
+
+/** Build definition-reference graph: referenced constituent → dependent (backend {@code graph_text}). */
+export function buildDefinitionReferenceGraph(items: readonly TextResolvableFields[]): Graph<number> {
+  return buildReferenceGraph(items, 'definition_raw');
+}
+
+/** Resolve all term and definition texts in topological order. Mutates items in place. */
+export function resolveAllConstituentTexts(items: TextResolvableFields[]): void {
+  const graphTerm = buildTermReferenceGraph(items);
+  const idToItem = new Map(items.map(item => [item.id, item]));
+  const context = buildTermContext(items);
+
+  for (const id of graphTerm.topologicalOrder()) {
+    const row = idToItem.get(id);
+    if (!row) {
+      continue;
+    }
+    const resolved = resolveTextReferences(row.term_raw, context);
+    if (resolved !== row.term_resolved) {
+      row.term_resolved = resolved;
+      row.term_forms = [];
+      context[row.alias] = { nominal: row.term_resolved, forms: [] };
+    }
+  }
+
+  for (const row of items) {
+    row.definition_resolved = resolveTextReferences(row.definition_raw, context);
+  }
+}
+
+/**
+ * Resolve texts after a single constituent change, cascading dependents when the term changed.
+ * Mutates items in place.
+ */
+export function resolveConstituentTextChange(
+  items: TextResolvableFields[],
+  targetID: number,
+  options: TextChangeOptions
+): void {
+  const idToItem = new Map(items.map(item => [item.id, item]));
+  const target = idToItem.get(targetID);
+  if (!target) {
+    throw new Error(`resolveConstituentTextChange: unknown target ${targetID}`);
+  }
+
+  const context = buildTermContext(items);
+  if (options.termRawChanged) {
+    target.term_resolved = resolveTextReferences(target.term_raw, context);
+    if (options.clearTargetForms) {
+      target.term_forms = [];
+    }
+    context[target.alias] = toContextItem(target);
+  } else if (options.termChanged) {
+    context[target.alias] = toContextItem(target);
+  }
+
+  if (options.definitionRawChanged && !options.termChanged) {
+    target.definition_resolved = resolveTextReferences(target.definition_raw, context);
+  }
+
+  if (!options.termChanged) {
+    return;
+  }
+
+  const graphTerm = buildTermReferenceGraph(items);
+  const graphText = buildDefinitionReferenceGraph(items);
+  const expansion = graphTerm.expandAllOutputs([targetID]);
+  const expansionSet = new Set(expansion);
+
+  for (const id of graphTerm.topologicalOrder()) {
+    if (!expansionSet.has(id)) {
+      continue;
+    }
+    const expanded = idToItem.get(id);
+    if (!expanded) {
+      continue;
+    }
+    const resolved = resolveTextReferences(expanded.term_raw, context);
+    if (resolved !== expanded.term_resolved) {
+      expanded.term_resolved = resolved;
+      expanded.term_forms = [];
+      context[expanded.alias] = { nominal: expanded.term_resolved, forms: [] };
+    }
+  }
+
+  const updateDefs = new Set([targetID, ...expansion, ...graphText.expandAllOutputs([targetID, ...expansion])]);
+  for (const item of items) {
+    if (updateDefs.has(item.id)) {
+      item.definition_resolved = resolveTextReferences(item.definition_raw, context);
+    }
+  }
+}
+
+// ====== Internals =======
+
+function buildReferenceGraph(
+  items: readonly TextResolvableFields[],
+  field: 'definition_raw' | 'term_raw'
+): Graph<number> {
+  const graph = new Graph<number>();
+  const idByAlias = new Map(items.map(row => [row.alias, row.id]));
+  for (const row of items) {
+    graph.addNode(row.id);
+  }
+  for (const row of items) {
+    for (const entity of extractEntities(row[field])) {
+      const source = idByAlias.get(entity);
+      if (source !== undefined) {
+        graph.addEdge(source, row.id);
+      }
+    }
+  }
+  return graph;
+}
+
+function buildTermContext(items: readonly TextResolvableFields[]): TermContext {
+  const context: TermContext = {};
+  for (const row of items) {
+    context[row.alias] = toContextItem(row);
+  }
+  return context;
+}
+
+function toContextItem(row: TextResolvableFields): TermContext[string] {
+  return {
+    nominal: row.term_resolved,
+    forms: row.term_forms.map(form => ({ text: form.text, grams: parseGrammemes(form.tags) }))
+  };
+}

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

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from '../rsform';
+
+import {
+  allocateImportAliases,
+  applyConstituentSubstitutions,
+  buildSequentialAliasMapping,
+  filterAttributions,
+  importAttributions,
+  insertItemAfter,
+  maxAliasIndex,
+  moveIdsInOrder,
+  remapAttributionsUnderSubstitution,
+  remapSubstitutionsAfterImport,
+  reorderItemsByIds
+} from './index';
+
+describe('maxAliasIndex / sequential and import aliases', () => {
+  it('finds max numeric suffix per type', () => {
+    expect(
+      maxAliasIndex(
+        [
+          { alias: 'X1', cst_type: CstType.BASE },
+          { alias: 'X4', cst_type: CstType.BASE }
+        ],
+        CstType.BASE
+      )
+    ).toBe(4);
+    expect(maxAliasIndex([{ alias: 'D2', cst_type: CstType.TERM }], CstType.BASE)).toBe(0);
+  });
+
+  it('builds sequential alias mapping in list order', () => {
+    const mapping = buildSequentialAliasMapping([
+      { alias: 'X9', cst_type: CstType.BASE },
+      { alias: 'X1', cst_type: CstType.BASE },
+      { alias: 'D5', cst_type: CstType.TERM }
+    ]);
+    expect(mapping).toEqual({ X9: 'X1', X1: 'X2', D5: 'D1' });
+  });
+
+  it('allocates import aliases only when receiver is non-empty', () => {
+    expect(allocateImportAliases([], [{ alias: 'X9', cst_type: CstType.BASE }])).toEqual({});
+    expect(
+      allocateImportAliases([{ alias: 'X2', cst_type: CstType.BASE }], [{ alias: 'X9', cst_type: CstType.BASE }])
+    ).toEqual({ X9: 'X3' });
+  });
+});
+
+describe('attribution remapping', () => {
+  it('remaps attributions under substitution and drops self-loops', () => {
+    const remapped = remapAttributionsUnderSubstitution(
+      [
+        { container: 1, attribute: 10 },
+        { container: 2, attribute: 20 },
+        { container: 1, attribute: 2 }
+      ],
+      new Map([
+        [1, 2],
+        [10, 20]
+      ])
+    );
+    expect(remapped).toEqual([{ container: 2, attribute: 20 }]);
+  });
+
+  it('imports attributions with id map and dedupe against existing', () => {
+    const imported = importAttributions(
+      [
+        { container: 10, attribute: 11 },
+        { container: 10, attribute: 99 }
+      ],
+      new Set([10, 11]),
+      { 10: 100, 11: 101 },
+      [{ container: 100, attribute: 101 }]
+    );
+    expect(imported).toEqual([{ container: 100, attribute: 101 }]);
+  });
+
+  it('filters attributions by deleted ids', () => {
+    expect(
+      filterAttributions(
+        [
+          { container: 1, attribute: 2 },
+          { container: 3, attribute: 4 }
+        ],
+        new Set([1])
+      )
+    ).toEqual([{ container: 3, attribute: 4 }]);
+  });
+});
+
+describe('transforms', () => {
+  it('moves ids within order', () => {
+    expect(moveIdsInOrder([1, 2, 3, 4], [2, 3], 0)).toEqual([2, 3, 1, 4]);
+    expect(moveIdsInOrder([1, 2, 3], [3], 99)).toEqual([1, 2, 3]);
+  });
+
+  it('reorders items by ids', () => {
+    const items = [
+      { id: 1, alias: 'a' },
+      { id: 2, alias: 'b' }
+    ];
+    expect(reorderItemsByIds(items, [2, 1]).map(i => i.alias)).toEqual(['b', 'a']);
+  });
+
+  it('inserts after id or appends', () => {
+    const items = [{ id: 1 }, { id: 2 }];
+    insertItemAfter(items, { id: 3 }, 1);
+    expect(items.map(i => i.id)).toEqual([1, 3, 2]);
+    insertItemAfter(items, { id: 4 }, null);
+    expect(items.map(i => i.id)).toEqual([1, 3, 2, 4]);
+  });
+});
+
+describe('substitution', () => {
+  it('applies alias mapping and drops originals', () => {
+    const items = [
+      {
+        id: 1,
+        alias: 'X1',
+        definition_formal: 'X1',
+        typification_manual: '',
+        term_raw: 'a',
+        definition_raw: '@{X1|nomn,sing}'
+      },
+      {
+        id: 2,
+        alias: 'X2',
+        definition_formal: 'X2',
+        typification_manual: '',
+        term_raw: 'b',
+        definition_raw: ''
+      }
+    ];
+    const result = applyConstituentSubstitutions(
+      items,
+      [{ container: 1, attribute: 2 }],
+      [{ original: 1, substitution: 2 }]
+    );
+    expect(result.deletedIds).toEqual(new Set([1]));
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0].definition_raw).toBe('');
+    expect(result.attributions).toEqual([]);
+  });
+
+  it('remaps substitutions after import', () => {
+    expect(
+      remapSubstitutionsAfterImport(
+        [
+          { original: 10, substitution: 1 },
+          { original: 1, substitution: 10 }
+        ],
+        new Set([10]),
+        { 10: 100 }
+      )
+    ).toEqual([
+      { original: 100, substitution: 1 },
+      { original: 1, substitution: 100 }
+    ]);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * Pure constituenta list transforms: reorder, move, insert position.
+ */
+
+/** Rebuild an item list following {@link orderedIds}. Throws if an id is missing. */
+export function reorderItemsByIds<T extends { id: number }>(items: readonly T[], orderedIds: readonly number[]): T[] {
+  const byId = new Map(items.map(item => [item.id, item]));
+  return orderedIds.map(id => {
+    const item = byId.get(id);
+    if (!item) {
+      throw new Error(`reorderItemsByIds: missing id ${id}`);
+    }
+    return item;
+  });
+}
+
+/**
+ * Move a subset of ids within an ordered id list.
+ * {@link moveTo} is clamped to `[0, rest.length]` (index among non-moving items).
+ */
+export function moveIdsInOrder(ids: readonly number[], moving: readonly number[], moveTo: number): number[] {
+  const movingSet = new Set(moving);
+  const rest = ids.filter(id => !movingSet.has(id));
+  const movingItems = ids.filter(id => movingSet.has(id));
+  const clamped = Math.max(0, Math.min(moveTo, rest.length));
+  return [...rest.slice(0, clamped), ...movingItems, ...rest.slice(clamped)];
+}
+
+/** Insert {@link item} after {@link insertAfter}, or append when null/undefined/missing. Mutates {@link items}. */
+export function insertItemAfter<T extends { id: number }>(
+  items: T[],
+  item: T,
+  insertAfter: number | null | undefined
+): void {
+  if (insertAfter === null || insertAfter === undefined) {
+    items.push(item);
+    return;
+  }
+  const idx = items.findIndex(row => row.id === insertAfter);
+  const insertAt = idx === -1 ? items.length : idx + 1;
+  items.splice(insertAt, 0, item);
+}

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

@@ -1,11 +1,15 @@
 /**
- * Types for restoring constituent declaration order.
+ * Capability field slices for schema transforms.
+ *
+ * Named by concern/task (*Fields), not as subtypes of Constituenta —
+ * same idea as ConceptCore's RSConcept / TextConcept split.
  */
 
-import { type CstType } from '../rsform';
+import { type ExpressionType, type TypePath } from '../../rslang';
+import { type CstStatus, type CstType, type TermForm } from '../rsform';
 
-/** Minimal constituent fields required to restore order. */
-export interface OrderableConstituenta {
+/** Fields needed to restore formal dependency order. */
+export interface FormalOrderFields {
   id: number;
   alias: string;
   cst_type: CstType;
@@ -19,3 +23,97 @@ export interface SemanticRelations {
   /** Semantic children ids for each constituenta. */
   childrenOf: Map<number, number[]>;
 }
+
+/** Fields needed to resolve term/definition entity references. */
+export interface TextResolvableFields {
+  id: number;
+  alias: string;
+  term_raw: string;
+  term_resolved: string;
+  term_forms: TermForm[];
+  definition_raw: string;
+  definition_resolved: string;
+}
+
+/** Fields needed to allocate or reset aliases by type. */
+export interface AliasTypedFields {
+  alias: string;
+  cst_type: CstType;
+}
+
+/** Fields needed to decide whether structure can be produced. */
+export interface StructureCapableFields {
+  cst_type: CstType;
+  effectiveType: ExpressionType | null;
+}
+
+/** Fields needed for schema-issue checks (status + diagnostics). */
+export interface SchemaIssueFields {
+  status: CstStatus;
+  diagnostics?: readonly { code: number }[] | null;
+}
+
+/** Fields needed to look up evaluation status for a model item. */
+export interface ModelEvalFields {
+  id: number;
+  cst_type: CstType;
+}
+
+/** Fields needed to check missing convention / resolved term on basics. */
+export interface BasicTextCheckFields {
+  cst_type: CstType;
+  convention: string;
+  term_resolved: string;
+}
+
+/** Fields needed to walk spawn paths for structure helpers. */
+export interface SpawnPathFields {
+  id: number;
+  spawner?: number;
+  spawner_path?: TypePath;
+}
+
+/** Fields needed to extract template parameters from a bank item. */
+export interface TemplateParamSourceFields {
+  definition_formal: string;
+  effectiveType: ExpressionType | null;
+}
+
+/** Fields copied from a template bank item when instantiating. */
+export interface TemplateSourceFields extends TemplateParamSourceFields {
+  alias: string;
+  cst_type: CstType;
+  crucial: boolean;
+  convention: string;
+  definition_raw: string;
+  term_raw: string;
+  term_forms: TermForm[];
+  typification_manual: string;
+  value_is_property: boolean;
+}
+
+/** Fields needed to expand schema/model diagnostics into expressions. */
+export interface DiagnosticSourceFields {
+  id: number;
+  alias: string;
+  cst_type: CstType;
+  term_resolved: string;
+  convention: string;
+  typification_manual: string;
+  definition_formal: string;
+}
+
+/** Fields needed for text search over constituenta content. */
+export interface SearchableFields {
+  alias: string;
+  cst_type: CstType;
+  term_raw: string;
+  term_resolved: string;
+  definition_formal: string;
+  definition_raw: string;
+  definition_resolved: string;
+  convention: string;
+}
+
+/** Fields needed to build short UI descriptions / labels. */
+export type DescribableFields = SearchableFields;

package/src/library/rsform.ts

@@ -68,7 +68,7 @@ export interface Substitution {
 }
 
 /** Represents word form for natural language. */
-interface TermForm {
+export interface TermForm {
   text: string;
   tags: string;
 }

package/src/library/rsmodel-api.ts

@@ -5,8 +5,8 @@ import { type EchelonCollection } from '../rslang/semantic/typification';
 
 import { modelStatusCstDiagnostic } from './diagnostics';
 import { type RSEngine } from './rsengine';
-import { type Constituenta, CstType, type RSForm } from './rsform';
-import { calculateSchemaStats, isBaseSet, isBasicConcept } from './rsform-api';
+import { CstType, type RSForm } from './rsform';
+import { calculateSchemaStats, isBaseSet, isBasicConcept, type ModelEvalFields } from './rsform-api';
 import { type BasicBinding, EvalStatus, type RSModelStats } from './rsmodel';
 
 const RANDOM_INTEGER_MIN = -100;
@@ -44,7 +44,7 @@ export function validateValueData(data: unknown): data is Value {
 export function generateRandomValue(
   type: Typification,
   basics: Map<number, BasicBinding>,
-  cstByAlias: Map<string, Constituenta>,
+  cstByAlias: Map<string, { id: number }>,
   setElementsCount: number = DEFAULT_RANDOM_SET_ELEMENTS_COUNT
 ): Value | null {
   switch (type.typeID) {
@@ -125,10 +125,15 @@ export function calculateModelStats(schema: RSForm, engine: RSEngine, _engineGen
 }
 
 /** Checks whether evaluation status contributes to model status issues. */
-export function isModelIssue(engine: RSEngine, cst: Constituenta): boolean {
+export function isModelIssue(engine: RSEngine, cst: ModelEvalFields): boolean {
   return modelStatusCstDiagnostic(engine.getCstStatus(cst.id), cst.cst_type) !== null;
 }
 
+/** Filters items whose evaluation status contributes to model issues. */
+export function getEvalIssueItems(items: readonly ModelEvalFields[], engine: RSEngine): ModelEvalFields[] {
+  return items.filter(cst => isModelIssue(engine, cst));
+}
+
 /** Evaluate if {@link CstType} is interpretable. */
 export function isInterpretable(type: CstType): boolean {
   switch (type) {
@@ -325,7 +330,7 @@ export function addValueElement(
 
 // ========= Internal functions ==========
 
-function countBaseElements(cst: Constituenta, engine: RSEngine): number {
+function countBaseElements(cst: ModelEvalFields, engine: RSEngine): number {
   if (!isBasicConcept(cst.cst_type)) {
     return 0;
   }

package/src/library/structure-planner.ts

@@ -4,7 +4,7 @@ import { labelType } from '../rslang/labels';
 import { bool, type EchelonFunctional, isTypification } from '../rslang/semantic/typification';
 
 import { type Constituenta, CstType, type RSForm } from './rsform';
-import { findCstByStructure } from './rsform-api';
+import { findCstByStructure, type FormalOrderFields, type StructureCapableFields } from './rsform-api';
 
 /** Represents a node in the structure planner. */
 export interface SPNode {
@@ -95,7 +95,11 @@ export class StructurePlanner {
 }
 
 // ======= Internals =======
-function produceDefinition(target: Constituenta, rootType: Typification, path: TypePath): string {
+function produceDefinition(
+  target: FormalOrderFields & StructureCapableFields,
+  rootType: Typification,
+  path: TypePath
+): string {
   let current = rootType;
   let expression = target.alias;
   let index = rootType.typeID === TypeID.collection ? 1 : 0;

package/src/library/template-instantiation.ts

@@ -16,14 +16,16 @@ import { labelType } from '../rslang/labels';
 import { TokenID } from '../rslang/parser/token';
 import { TypeID } from '../rslang/semantic/typification';
 
-import { type ArgumentValue, type Constituenta, type CstType, type RSForm } from './rsform';
+import { type ArgumentValue, type CstType, type RSForm, type TermForm } from './rsform';
 import {
   applyMappingToConstituents,
   argumentValuesToMapping,
   generateAlias,
   inferTemplatedType,
   isFunctional,
-  normalizeExpression
+  normalizeExpression,
+  type TemplateParamSourceFields,
+  type TemplateSourceFields
 } from './rsform-api';
 
 /**
@@ -42,7 +44,7 @@ export interface TemplateInstantiationItem {
   definition_formal: string;
   definition_raw: string;
   term_raw: string;
-  term_forms: Constituenta['term_forms'];
+  term_forms: TermForm[];
   typification_manual: string;
   value_is_property: boolean;
 }
@@ -78,9 +80,9 @@ export interface TemplateInstantiationInput {
   /** Schema that will receive new constituents. */
   targetSchema: RSForm;
   /** All constituents of the selected expression-bank RSForm (not only the prototype). */
-  templateItems: Constituenta[];
+  templateItems: TemplateSourceFields[];
   /** Template constituent chosen in the UI (main expression to add). */
-  prototype: Constituenta;
+  prototype: TemplateSourceFields;
   /** User bindings from template parameter aliases to target-schema global aliases. */
   userArgs: ArgumentValue[];
   /**
@@ -118,10 +120,10 @@ export function planTemplateInstantiation(input: TemplateInstantiationInput): Te
  */
 export class TemplateInstantiationPlanner {
   private readonly targetSchema: RSForm;
-  private readonly prototype: Constituenta;
+  private readonly prototype: TemplateSourceFields;
   private readonly userArgs: ArgumentValue[];
   private readonly mainItemTemplate: TemplateInstantiationItem;
-  private readonly templateByAlias: Map<string, Constituenta>;
+  private readonly templateByAlias: Map<string, TemplateSourceFields>;
   private readonly userMapping: AliasMapping;
   private readonly depBindings = new Map<string, Map<string, string>>();
   private readonly depRefs = new Map<string, Set<string>>();
@@ -322,7 +324,7 @@ function formalDefinitionKey(cst_type: CstType, normalized: string): string {
 }
 
 function instantiateTemplateItem(
-  template: Constituenta,
+  template: TemplateSourceFields,
   args: ArgumentValue[],
   alias: string
 ): TemplateInstantiationItem {
@@ -384,7 +386,7 @@ function bindingMapToArgs(params: TemplateParam[], bindings: Map<string, string>
   }));
 }
 
-function getTemplateParams(template: Constituenta): TemplateParam[] {
+function getTemplateParams(template: TemplateParamSourceFields): TemplateParam[] {
   const effectiveType = template.effectiveType;
   if (effectiveType && (effectiveType.typeID === TypeID.function || effectiveType.typeID === TypeID.predicate)) {
     return effectiveType.args.map(arg => ({