@transitrix/diagrams 1.16.0 → 1.17.0

package/dist/actor/types.d.ts

@@ -6,7 +6,7 @@ export type ActorType = typeof ACTOR_TYPES[number];
  * inline on an ACTOR file (§7.10, ACTOR-003). They belong in time-aware REL
  * records, never on the identity primitive.
  */
-export declare const ACTOR_FORBIDDEN_INLINE_FIELDS: readonly ["employment", "candidacy", "alumni_membership", "community_membership", "contracting", "unit_parent", "located_at", "unit_located_at", "roles", "owner"];
+export declare const ACTOR_FORBIDDEN_INLINE_FIELDS: readonly ["employment", "candidacy", "alumni_membership", "community_membership", "contracting", "unit_parent", "reports_to", "manager", "located_at", "unit_located_at", "roles", "owner"];
 export interface Actor {
     notation: 'actor';
     id: string;

package/dist/actor/types.js

@@ -13,6 +13,8 @@ export const ACTOR_FORBIDDEN_INLINE_FIELDS = [
     'community_membership',
     'contracting',
     'unit_parent',
+    'reports_to',
+    'manager',
     'located_at',
     'unit_located_at',
     'roles',

package/dist/goals/resolver.d.ts

@@ -47,6 +47,7 @@ export interface GoalsViewConfig {
 }
 export interface GoalsCanonSources {
     elements: unknown[];
+    relations?: unknown[];
 }
 /**
  * Returns true when the parsed view document uses the canon-projection form

package/dist/goals/resolver.js

@@ -42,10 +42,51 @@ function collectGoalElements(docs) {
         if (!id)
             continue;
         if (!out.has(id))
-            out.set(id, doc); // first definition wins
+            out.set(id, { ...doc }); // never mutate the caller's catalogue
     }
     return out;
 }
+/** Materialize canonical child -> parent links for a single-parent tree.
+ * Never mutate canon or silently linearize an ambiguous hierarchy.
+ */
+function applyGoalParentRelations(goals, relations, validAt) {
+    const declaredChildren = new Set();
+    const parents = new Map();
+    for (const doc of relations) {
+        if (!isObject(doc) || doc['notation'] !== 'relation' || doc['type'] !== 'goal_parent')
+            continue;
+        const child = str(doc['from']);
+        const parent = str(doc['to']);
+        if (!child || !parent || !goals.has(child) || !goals.has(parent)) {
+            throw new Error(`goal_parent relation ${str(doc['id']) ?? '(unnamed)'} must reference two existing goals`);
+        }
+        declaredChildren.add(child);
+        const from = str(doc['valid_from']);
+        const to = str(doc['valid_to']);
+        if (validAt && ((from && validAt < from) || (to && validAt > to)))
+            continue;
+        const choices = parents.get(child) ?? new Set();
+        choices.add(parent);
+        parents.set(child, choices);
+    }
+    for (const child of declaredChildren) {
+        const goal = goals.get(child);
+        const choices = parents.get(child) ?? new Set();
+        if (choices.size > 1) {
+            throw new Error(`goal_parent for ${child} has multiple parents in this scope; narrow valid_at or use a graph view`);
+        }
+        const parent = [...choices][0];
+        const legacyParent = str(goal['parent']);
+        if (parent && legacyParent && parent !== legacyParent) {
+            throw new Error(`goal_parent for ${child} conflicts with its inline parent`);
+        }
+        // Declared but inactive links must not fall back to an undated parent.
+        if (parent)
+            goal['parent'] = parent;
+        else
+            delete goal['parent'];
+    }
+}
 /**
  * Returns true when the parsed view document uses the canon-projection form
  * (`view_config` key present, no inline `goals[]`). Used by the preview and
@@ -69,6 +110,8 @@ export function resolveGoals(viewDoc, sources) {
     const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
     const scope = isObject(vc['scope']) ? vc['scope'] : {};
     const allGoals = collectGoalElements(sources.elements);
+    const validAt = str(scope['valid_at']);
+    applyGoalParentRelations(allGoals, sources.relations ?? [], validAt);
     // 1. Scope by root_goal (this goal + its descendants), or every goal when
     // omitted (§5.1: "Omit to show all root goals").
     const rootGoal = str(scope['root_goal']);
@@ -97,7 +140,6 @@ export function resolveGoals(viewDoc, sources) {
     // 4. Narrow by valid_at — only goals in effect on that date. Goals with no
     // valid_from are not lifecycle-tracked and are kept (permissive default,
     // matching the action/dgca resolvers' stance).
-    const validAt = str(scope['valid_at']);
     if (validAt) {
         candidateIds = new Set([...candidateIds].filter((id) => {
             const el = allGoals.get(id);

package/dist/repo-validate/check-strategy-chain.js

@@ -17,16 +17,11 @@ import { validateActionFields } from '../activities/action-fields.js';
 // classification (`Issue.Severity` in the Go source) and its "import
 // anyway, record the warning" policy.
 //
-// GOALS-009/011 (orphan / missing parent) are ported at warning severity even
-// though most standalone GOAL elements legitimately have no `parent` field —
-// GOAL.parent is "v0.x transitional" (ELEMENT_PRIMITIVES.md §7.2; canonical
-// home is a `goal_parent` REL file or the goals-tree view's inline `parent`).
-// `organizations/acme_corp`'s GOAL-CUST-1/GOAL-OPS-1/GOAL-EU-1 are exactly
-// this shape and do surface GOALS-011 warnings — that noise is the accepted
-// cost of a *warning* level rule (non-blocking, advisory), unlike the ERROR
-// tier this repo held the line on. This is a deliberate call, not an
-// oversight: keep the coverage rather than drop it, now that it can be
-// non-blocking.
+// GOALS-010 checks canonical and legacy edges in overlapping lifecycle slices.
+// GOALS-009/011 respect the canonical goal_parent records already loaded
+// from canon/relations. Static catalogue coverage considers those links;
+// date-scoped hierarchy selection and ambiguity are checked by Goals views.
+// Legacy inline parents remain supported for transitional catalogues.
 //
 // GOALS-008 (type/level mismatch) is still NOT ported, at either severity.
 // Both of DSM's cases ("type not declared in goal_types" / "level doesn't
@@ -107,17 +102,15 @@ function collectByNotation(elements, matches) {
     }
     return out;
 }
-/** DFS cycle detection over a single-parent edge (GOAL.parent), matching DSM's
+/** DFS cycle detection over resolved parent edges, matching DSM's
  *  `findCycle` (goals.go): only walks an edge to a parent that itself resolves
  *  within the set — an edge into an unresolved (orphan) parent is not walked,
  *  so an orphan can never be mistaken for a cycle. Returns the id where a
  *  back-edge was hit, or `undefined` if the graph is acyclic. */
-function findParentCycle(goals) {
-    const parentOf = new Map();
+function findParentCycle(goals, parents) {
     const known = new Set();
     for (const g of goals) {
         known.add(g.id);
-        parentOf.set(g.id, readString(g.data, 'parent'));
     }
     const UNVISITED = 0;
     const VISITING = 1;
@@ -130,8 +123,9 @@ function findParentCycle(goals) {
         if (s === VISITING)
             return id;
         state.set(id, VISITING);
-        const parent = parentOf.get(id);
-        if (parent && known.has(parent)) {
+        for (const parent of parents.get(id) ?? []) {
+            if (!known.has(parent))
+                continue;
             const hit = walk(parent);
             if (hit)
                 return hit;
@@ -184,27 +178,68 @@ function findPredecessorCycle(actions) {
     }
     return undefined;
 }
-/** GOALS-010 — the GOAL `parent` chain must not contain a cycle. */
-function checkGoalParentCycle(goals, findings) {
-    const cyc = findParentCycle(goals);
-    if (cyc) {
+/** GOALS-010 — parent links must be acyclic in every effective date slice.
+ * A cycle can first appear only when an edge starts. Inspect those boundaries
+ * and the unbounded past; do not union disjoint historical parent relations.
+ */
+function checkGoalParentCycle(goals, relations, findings) {
+    const known = new Set(goals.map(g => g.id));
+    const links = relations.flatMap(rel => {
+        const d = rel.data;
+        if (!d || d['notation'] !== 'relation' || d['type'] !== 'goal_parent')
+            return [];
+        const child = readString(d, 'from'), parent = readString(d, 'to');
+        if (!child || !parent || !known.has(child) || !known.has(parent))
+            return [];
+        return [{ child, parent, from: readString(d, 'valid_from'), to: readString(d, 'valid_to') }];
+    });
+    const declared = new Set(links.map(link => link.child));
+    const dates = [...new Set(['0000-01-01', ...links.flatMap(link => link.from ? [link.from] : [])])].sort();
+    for (const date of dates) {
+        const parents = new Map();
+        for (const g of goals) {
+            const legacy = readString(g.data, 'parent');
+            if (!declared.has(g.id) && legacy)
+                parents.set(g.id, [legacy]);
+        }
+        for (const link of links) {
+            if ((link.from && date < link.from) || (link.to && date > link.to))
+                continue;
+            parents.set(link.child, [...(parents.get(link.child) ?? []), link.parent]);
+        }
+        const cyc = findParentCycle(goals, parents);
+        if (!cyc)
+            continue;
         findings.push({
             scope: PScope,
             id: cyc,
             ruleId: 'GOALS-010',
             message: `GOALS-010: parent chain contains a cycle involving goal '${cyc}'.`,
         });
+        return;
     }
 }
 /** GOALS-009 / GOALS-011 — GOAL `parent` resolution (warning). Mirrors DSM's
  *  goals.go: the two are mutually exclusive per goal — a goal with no
  *  `parent` is checked for GOALS-011 (backlog, level >= 1); a goal with a
  *  `parent` is checked for GOALS-009 (orphan, parent unresolved) instead. */
-function checkGoalParentResolution(goals, findings) {
+function checkGoalParentResolution(goals, relations, findings) {
     const knownIds = new Set(goals.map((g) => g.id));
+    const linkedChildren = new Set();
+    for (const rel of relations) {
+        const data = rel.data;
+        if (!data || data['notation'] !== 'relation' || data['type'] !== 'goal_parent')
+            continue;
+        const child = readString(data, 'from');
+        const parent = readString(data, 'to');
+        if (child && parent && knownIds.has(child) && knownIds.has(parent))
+            linkedChildren.add(child);
+    }
     for (const g of goals) {
         const parent = readString(g.data, 'parent');
         if (!parent) {
+            if (linkedChildren.has(g.id))
+                continue;
             const level = readFiniteNumber(g.data, 'level');
             if (level !== undefined && level >= 1) {
                 findings.push({
@@ -467,8 +502,8 @@ export function checkStrategyChainSemantics(input, findings) {
     const actions = collectByNotation(input.elements, isActionNotation);
     const drivers = collectByNotation(input.elements, isDriverNotation);
     const changes = collectByNotation(input.elements, isChangeNotation);
-    checkGoalParentCycle(goals, findings);
-    checkGoalParentResolution(goals, findings);
+    checkGoalParentCycle(goals, input.relations, findings);
+    checkGoalParentResolution(goals, input.relations, findings);
     checkActionSelfPredecessor(actions, findings);
     checkActionPredecessorCycle(actions, findings);
     checkActionOrphanReferences(actions, findings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/actor/types.ts

@@ -18,6 +18,8 @@ export const ACTOR_FORBIDDEN_INLINE_FIELDS = [
   'community_membership',
   'contracting',
   'unit_parent',
+  'reports_to',
+  'manager',
   'located_at',
   'unit_located_at',
   'roles',

package/src/goals/resolver.ts

@@ -48,6 +48,7 @@ export interface GoalsViewConfig {
 
 export interface GoalsCanonSources {
   elements: unknown[];
+  relations?: unknown[];
 }
 
 /** GOAL elements by id (`notation: goal`). */
@@ -58,11 +59,53 @@ function collectGoalElements(docs: unknown[]): Map<string, Record<string, unknow
     if (str(doc['notation']) !== 'goal') continue;
     const id = str(doc['id']);
     if (!id) continue;
-    if (!out.has(id)) out.set(id, doc); // first definition wins
+    if (!out.has(id)) out.set(id, { ...doc }); // never mutate the caller's catalogue
   }
   return out;
 }
 
+/** Materialize canonical child -> parent links for a single-parent tree.
+ * Never mutate canon or silently linearize an ambiguous hierarchy.
+ */
+function applyGoalParentRelations(
+  goals: Map<string, Record<string, unknown>>,
+  relations: unknown[],
+  validAt: string | undefined,
+): void {
+  const declaredChildren = new Set<string>();
+  const parents = new Map<string, Set<string>>();
+  for (const doc of relations) {
+    if (!isObject(doc) || doc['notation'] !== 'relation' || doc['type'] !== 'goal_parent') continue;
+    const child = str(doc['from']);
+    const parent = str(doc['to']);
+    if (!child || !parent || !goals.has(child) || !goals.has(parent)) {
+      throw new Error(`goal_parent relation ${str(doc['id']) ?? '(unnamed)'} must reference two existing goals`);
+    }
+    declaredChildren.add(child);
+    const from = str(doc['valid_from']);
+    const to = str(doc['valid_to']);
+    if (validAt && ((from && validAt < from) || (to && validAt > to))) continue;
+    const choices = parents.get(child) ?? new Set<string>();
+    choices.add(parent);
+    parents.set(child, choices);
+  }
+  for (const child of declaredChildren) {
+    const goal = goals.get(child)!;
+    const choices = parents.get(child) ?? new Set<string>();
+    if (choices.size > 1) {
+      throw new Error(`goal_parent for ${child} has multiple parents in this scope; narrow valid_at or use a graph view`);
+    }
+    const parent = [...choices][0];
+    const legacyParent = str(goal['parent']);
+    if (parent && legacyParent && parent !== legacyParent) {
+      throw new Error(`goal_parent for ${child} conflicts with its inline parent`);
+    }
+    // Declared but inactive links must not fall back to an undated parent.
+    if (parent) goal['parent'] = parent;
+    else delete goal['parent'];
+  }
+}
+
 /**
  * Returns true when the parsed view document uses the canon-projection form
  * (`view_config` key present, no inline `goals[]`). Used by the preview and
@@ -91,6 +134,8 @@ export function resolveGoals(
   const scope = isObject(vc['scope']) ? vc['scope'] : {};
 
   const allGoals = collectGoalElements(sources.elements);
+  const validAt = str(scope['valid_at']);
+  applyGoalParentRelations(allGoals, sources.relations ?? [], validAt);
 
   // 1. Scope by root_goal (this goal + its descendants), or every goal when
   // omitted (§5.1: "Omit to show all root goals").
@@ -126,7 +171,6 @@ export function resolveGoals(
   // 4. Narrow by valid_at — only goals in effect on that date. Goals with no
   // valid_from are not lifecycle-tracked and are kept (permissive default,
   // matching the action/dgca resolvers' stance).
-  const validAt = str(scope['valid_at']);
   if (validAt) {
     candidateIds = new Set(
       [...candidateIds].filter((id) => {

package/src/repo-validate/check-strategy-chain.ts

@@ -17,16 +17,11 @@ import { validateActionFields } from '../activities/action-fields.js';
 // classification (`Issue.Severity` in the Go source) and its "import
 // anyway, record the warning" policy.
 //
-// GOALS-009/011 (orphan / missing parent) are ported at warning severity even
-// though most standalone GOAL elements legitimately have no `parent` field —
-// GOAL.parent is "v0.x transitional" (ELEMENT_PRIMITIVES.md §7.2; canonical
-// home is a `goal_parent` REL file or the goals-tree view's inline `parent`).
-// `organizations/acme_corp`'s GOAL-CUST-1/GOAL-OPS-1/GOAL-EU-1 are exactly
-// this shape and do surface GOALS-011 warnings — that noise is the accepted
-// cost of a *warning* level rule (non-blocking, advisory), unlike the ERROR
-// tier this repo held the line on. This is a deliberate call, not an
-// oversight: keep the coverage rather than drop it, now that it can be
-// non-blocking.
+// GOALS-010 checks canonical and legacy edges in overlapping lifecycle slices.
+// GOALS-009/011 respect the canonical goal_parent records already loaded
+// from canon/relations. Static catalogue coverage considers those links;
+// date-scoped hierarchy selection and ambiguity are checked by Goals views.
+// Legacy inline parents remain supported for transitional catalogues.
 //
 // GOALS-008 (type/level mismatch) is still NOT ported, at either severity.
 // Both of DSM's cases ("type not declared in goal_types" / "level doesn't
@@ -124,17 +119,15 @@ function collectByNotation(
   return out;
 }
 
-/** DFS cycle detection over a single-parent edge (GOAL.parent), matching DSM's
+/** DFS cycle detection over resolved parent edges, matching DSM's
  *  `findCycle` (goals.go): only walks an edge to a parent that itself resolves
  *  within the set — an edge into an unresolved (orphan) parent is not walked,
  *  so an orphan can never be mistaken for a cycle. Returns the id where a
  *  back-edge was hit, or `undefined` if the graph is acyclic. */
-function findParentCycle(goals: ChainElement[]): string | undefined {
-  const parentOf = new Map<string, string | undefined>();
+function findParentCycle(goals: ChainElement[], parents: Map<string, string[]>): string | undefined {
   const known = new Set<string>();
   for (const g of goals) {
     known.add(g.id);
-    parentOf.set(g.id, readString(g.data, 'parent'));
   }
   const UNVISITED = 0;
   const VISITING = 1;
@@ -146,8 +139,8 @@ function findParentCycle(goals: ChainElement[]): string | undefined {
     if (s === DONE) return undefined;
     if (s === VISITING) return id;
     state.set(id, VISITING);
-    const parent = parentOf.get(id);
-    if (parent && known.has(parent)) {
+    for (const parent of parents.get(id) ?? []) {
+      if (!known.has(parent)) continue;
       const hit = walk(parent);
       if (hit) return hit;
     }
@@ -198,16 +191,40 @@ function findPredecessorCycle(actions: ChainElement[]): string | undefined {
   return undefined;
 }
 
-/** GOALS-010 — the GOAL `parent` chain must not contain a cycle. */
-function checkGoalParentCycle(goals: ChainElement[], findings: RepoFinding[]): void {
-  const cyc = findParentCycle(goals);
-  if (cyc) {
+/** GOALS-010 — parent links must be acyclic in every effective date slice.
+ * A cycle can first appear only when an edge starts. Inspect those boundaries
+ * and the unbounded past; do not union disjoint historical parent relations.
+ */
+function checkGoalParentCycle(goals: ChainElement[], relations: RepoDoc[], findings: RepoFinding[]): void {
+  const known = new Set(goals.map(g => g.id));
+  const links = relations.flatMap(rel => {
+    const d = rel.data;
+    if (!d || d['notation'] !== 'relation' || d['type'] !== 'goal_parent') return [];
+    const child = readString(d, 'from'), parent = readString(d, 'to');
+    if (!child || !parent || !known.has(child) || !known.has(parent)) return [];
+    return [{ child, parent, from: readString(d, 'valid_from'), to: readString(d, 'valid_to') }];
+  });
+  const declared = new Set(links.map(link => link.child));
+  const dates = [...new Set(['0000-01-01', ...links.flatMap(link => link.from ? [link.from] : [])])].sort();
+  for (const date of dates) {
+    const parents = new Map<string, string[]>();
+    for (const g of goals) {
+      const legacy = readString(g.data, 'parent');
+      if (!declared.has(g.id) && legacy) parents.set(g.id, [legacy]);
+    }
+    for (const link of links) {
+      if ((link.from && date < link.from) || (link.to && date > link.to)) continue;
+      parents.set(link.child, [...(parents.get(link.child) ?? []), link.parent]);
+    }
+    const cyc = findParentCycle(goals, parents);
+    if (!cyc) continue;
     findings.push({
       scope: PScope,
       id: cyc,
       ruleId: 'GOALS-010',
       message: `GOALS-010: parent chain contains a cycle involving goal '${cyc}'.`,
     });
+    return;
   }
 }
 
@@ -215,11 +232,20 @@ function checkGoalParentCycle(goals: ChainElement[], findings: RepoFinding[]): v
  *  goals.go: the two are mutually exclusive per goal — a goal with no
  *  `parent` is checked for GOALS-011 (backlog, level >= 1); a goal with a
  *  `parent` is checked for GOALS-009 (orphan, parent unresolved) instead. */
-function checkGoalParentResolution(goals: ChainElement[], findings: RepoFinding[]): void {
+function checkGoalParentResolution(goals: ChainElement[], relations: RepoDoc[], findings: RepoFinding[]): void {
   const knownIds = new Set(goals.map((g) => g.id));
+  const linkedChildren = new Set<string>();
+  for (const rel of relations) {
+    const data = rel.data;
+    if (!data || data['notation'] !== 'relation' || data['type'] !== 'goal_parent') continue;
+    const child = readString(data, 'from');
+    const parent = readString(data, 'to');
+    if (child && parent && knownIds.has(child) && knownIds.has(parent)) linkedChildren.add(child);
+  }
   for (const g of goals) {
     const parent = readString(g.data, 'parent');
     if (!parent) {
+      if (linkedChildren.has(g.id)) continue;
       const level = readFiniteNumber(g.data, 'level');
       if (level !== undefined && level >= 1) {
         findings.push({
@@ -504,8 +530,8 @@ export function checkStrategyChainSemantics(input: RepoModelInput, findings: Rep
   const drivers = collectByNotation(input.elements, isDriverNotation);
   const changes = collectByNotation(input.elements, isChangeNotation);
 
-  checkGoalParentCycle(goals, findings);
-  checkGoalParentResolution(goals, findings);
+  checkGoalParentCycle(goals, input.relations, findings);
+  checkGoalParentResolution(goals, input.relations, findings);
   checkActionSelfPredecessor(actions, findings);
   checkActionPredecessorCycle(actions, findings);
   checkActionOrphanReferences(actions, findings);