@transitrix/diagrams 1.8.8 → 1.8.13

package/dist/activities/index.d.ts

@@ -3,3 +3,5 @@ export { validateActivities } from './validate.js';
 export { computeCpm } from './cpm.js';
 export { layoutActivities } from './layout.js';
 export { computeGanttLayout, isGanttUnavailable } from './gantt.js';
+export { resolveAction, isActionViewDoc } from './resolver.js';
+export type { ActionViewConfig, ActionCanonSources } from './resolver.js';

package/dist/activities/index.js

@@ -2,3 +2,4 @@ export { validateActivities } from './validate.js';
 export { computeCpm } from './cpm.js';
 export { layoutActivities } from './layout.js';
 export { computeGanttLayout, isGanttUnavailable } from './gantt.js';
+export { resolveAction, isActionViewDoc } from './resolver.js';

package/dist/activities/resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Action Schedule canon resolver — assembles a flat canonical Action document
+ * from a view_config projection and a canon element store (methodology
+ * `notations/views/07-action.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * pattern for the `action` notation.
+ *
+ * Output shape matches the flat inline form `validateActivities` expects:
+ * top-level `project` block + `actions[]`, with ACTION element fields carried
+ * through unchanged except `type` → `activity_type` (the internal Activity
+ * field name; `type` is the canonical element field per elements/24-action.md
+ * §2). Filesystem-free — callable from unit tests without vscode.
+ */
+export interface ActionViewConfig {
+    scope?: {
+        root_action?: string;
+        goals?: string[];
+        type_filter?: string[];
+        valid_at?: string | null;
+    };
+    schedule?: {
+        start_date?: string;
+        calendar?: {
+            working_days?: string[];
+            hours_per_day?: number;
+            holidays?: string[];
+        };
+    };
+    display?: {
+        view?: 'network' | 'gantt' | 'both';
+        depth?: number | null;
+        collapsed?: string[];
+    };
+}
+export interface ActionCanonSources {
+    elements: unknown[];
+    /** `canon/relations/**` docs (`notation: relation`). Optional — omit for
+     *  canon stores with no relations tree; `action_goal` links then fall back
+     *  to each element's inline `goals[]`. */
+    relations?: unknown[];
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `actions[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `validateActivities` on the inline document.
+ */
+export declare function isActionViewDoc(parsed: unknown): boolean;
+/**
+ * Assemble a flat canonical Action document from the canon ACTION element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `validateActivities`.
+ */
+export declare function resolveAction(viewDoc: unknown, sources: ActionCanonSources): Record<string, unknown>;

package/dist/activities/resolver.js

@@ -0,0 +1,172 @@
+/**
+ * Action Schedule canon resolver — assembles a flat canonical Action document
+ * from a view_config projection and a canon element store (methodology
+ * `notations/views/07-action.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * pattern for the `action` notation.
+ *
+ * Output shape matches the flat inline form `validateActivities` expects:
+ * top-level `project` block + `actions[]`, with ACTION element fields carried
+ * through unchanged except `type` → `activity_type` (the internal Activity
+ * field name; `type` is the canonical element field per elements/24-action.md
+ * §2). Filesystem-free — callable from unit tests without vscode.
+ */
+import { isObject, str, strArray, descendantsOf, stripEnvelope } from '../canon-resolver-utils.js';
+/** ACTION elements by id. `notation: action` is canonical; `notation: activity`
+ *  is the deprecated pre-2026-06-25 alias (elements/24-action.md §"Deprecated
+ *  alias") — accepted the same way `collectByNotation` callers elsewhere do. */
+function collectActionElements(docs) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isObject(doc))
+            continue;
+        const notation = str(doc['notation']);
+        if (notation !== 'action' && notation !== 'activity')
+            continue;
+        const id = str(doc['id']);
+        if (!id)
+            continue;
+        if (!out.has(id))
+            out.set(id, doc); // first definition wins
+    }
+    return out;
+}
+/**
+ * GOAL ids reached by an *active* `action_goal` (or legacy `activity_goal`)
+ * relation originating at `fromId`. A relation with a non-null `valid_to` has
+ * ended (the action was re-aimed) and is excluded. Mirrors
+ * `activity-card/resolver.ts`'s `activeActivityGoals` — the canonical, preferred
+ * source per elements/24-action.md §3 ("renderers prefer REL files when both
+ * are present").
+ */
+function activeActionGoalRelations(relations, fromId) {
+    const out = [];
+    for (const doc of relations) {
+        if (!isObject(doc))
+            continue;
+        if (str(doc['notation']) !== 'relation')
+            continue;
+        const type = str(doc['type']);
+        if (type !== 'action_goal' && type !== 'activity_goal')
+            continue;
+        if (str(doc['from']) !== fromId)
+            continue;
+        const to = str(doc['to']);
+        if (!to)
+            continue;
+        const validTo = doc['valid_to'];
+        if (validTo !== undefined && validTo !== null)
+            continue; // ended relation
+        if (!out.includes(to))
+            out.push(to);
+    }
+    return out;
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `actions[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `validateActivities` on the inline document.
+ */
+export function isActionViewDoc(parsed) {
+    if (!isObject(parsed))
+        return false;
+    return 'view_config' in parsed && !('actions' in parsed);
+}
+/**
+ * Assemble a flat canonical Action document from the canon ACTION element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `validateActivities`.
+ */
+export function resolveAction(viewDoc, sources) {
+    if (!isObject(viewDoc)) {
+        return { notation: 'action', actions: [] };
+    }
+    const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
+    const scope = isObject(vc['scope']) ? vc['scope'] : {};
+    const schedule = isObject(vc['schedule']) ? vc['schedule'] : {};
+    const allActions = collectActionElements(sources.elements);
+    const relations = sources.relations ?? [];
+    /** Effective `goals[]` for an action — the active `action_goal` REL targets
+     *  when any exist, else the element's transitional inline `goals[]`. */
+    function effectiveGoals(id, el) {
+        const relGoals = activeActionGoalRelations(relations, id);
+        return relGoals.length > 0 ? relGoals : strArray(el['goals']);
+    }
+    // 1. Scope by root_action (this action + its descendants), or the full
+    // catalogue when omitted (§5.1: "Omit to include elements from the full
+    // catalogue (or use goals/type_filter for other scoping)").
+    const rootAction = str(scope['root_action']);
+    let candidateIds;
+    if (rootAction) {
+        candidateIds = allActions.has(rootAction) ? descendantsOf(rootAction, allActions) : new Set();
+    }
+    else {
+        candidateIds = new Set(allActions.keys());
+    }
+    // 2. Narrow by goals — only actions linked to at least one listed GOAL
+    // (via an active action_goal relation, or inline goals[] when no relation
+    // exists for that action).
+    const goalsFilter = strArray(scope['goals']);
+    if (goalsFilter.length > 0) {
+        candidateIds = new Set([...candidateIds].filter((id) => effectiveGoals(id, allActions.get(id)).some((g) => goalsFilter.includes(g))));
+    }
+    // 3. Narrow by type_filter — only actions of a listed type.
+    const typeFilter = strArray(scope['type_filter']);
+    if (typeFilter.length > 0) {
+        candidateIds = new Set([...candidateIds].filter((id) => {
+            const el = allActions.get(id);
+            const t = str(el?.['type']) ?? str(el?.['activity_type']);
+            return t !== undefined && typeFilter.includes(t);
+        }));
+    }
+    // 4. Narrow by valid_at — only actions in effect on that date. Actions with
+    // no valid_from are not lifecycle-tracked and are kept (permissive default,
+    // matching the resolver's general "missing = not excluded" stance).
+    const validAt = str(scope['valid_at']);
+    if (validAt) {
+        candidateIds = new Set([...candidateIds].filter((id) => {
+            const el = allActions.get(id);
+            const from = str(el?.['valid_from']);
+            const to = str(el?.['valid_to']);
+            if (from && validAt < from)
+                return false;
+            if (to && validAt > to)
+                return false;
+            return true;
+        }));
+    }
+    // Element fields map onto Activity fields unchanged, except the canonical
+    // `type` (elements/24-action.md §2) which becomes the internal `activity_type`
+    // (types.ts `Activity.activity_type`), and `goals` which is resolved via
+    // `effectiveGoals` (REL-preferred). The admission/lifecycle envelope fields
+    // carry no schedule/render meaning for `validateActivities` and are dropped.
+    const selectedActions = [...candidateIds].map((id) => {
+        const el = allActions.get(id);
+        const { type, activity_type, goals: _inlineGoals, ...rest } = stripEnvelope(el);
+        const resolvedType = type ?? activity_type;
+        return {
+            ...rest,
+            id,
+            goals: effectiveGoals(id, el),
+            ...(resolvedType !== undefined ? { activity_type: resolvedType } : {}),
+        };
+    });
+    const project = {};
+    const startDate = str(schedule['start_date']);
+    if (startDate)
+        project['start_date'] = startDate;
+    if (isObject(schedule['calendar']))
+        project['calendar'] = schedule['calendar'];
+    const out = {
+        notation: 'action',
+        id: viewDoc['id'],
+        title: viewDoc['name'],
+        spec_version: viewDoc['spec_version'],
+        description: viewDoc['description'],
+        actions: selectedActions,
+    };
+    if (Object.keys(project).length > 0)
+        out['project'] = project;
+    return out;
+}

package/dist/canon-resolver-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared primitives for the per-notation canon-projection resolvers
+ * (activities/resolver.ts, goals/resolver.ts — fgca/resolver.ts predates this
+ * module and keeps its own copies). Each resolver assembles a flat document
+ * from a canon element store filtered by a view_config.scope block; these
+ * helpers are the parts that don't vary by notation.
+ */
+export declare function isObject(v: unknown): v is Record<string, unknown>;
+/** A non-empty string, trimmed. */
+export declare function str(v: unknown): string | undefined;
+export declare function strArray(v: unknown): string[];
+/** `rootId` and every element reachable by following `parent` links downward,
+ *  per the element map's own `parent` field. Used to scope a projection to a
+ *  root element and its transitive descendants (WBS / goal hierarchy / etc). */
+export declare function descendantsOf(rootId: string, all: Map<string, Record<string, unknown>>): Set<string>;
+/** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
+ *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
+ *  memoized across calls via the shared `memo` map. */
+export declare function parentChainDepth(id: string, all: Map<string, Record<string, unknown>>, memo?: Map<string, number>, visiting?: Set<string>): number;
+/** `el` with the admission/lifecycle envelope fields removed. */
+export declare function stripEnvelope(el: Record<string, unknown>): Record<string, unknown>;

package/dist/canon-resolver-utils.js

@@ -0,0 +1,81 @@
+/**
+ * Shared primitives for the per-notation canon-projection resolvers
+ * (activities/resolver.ts, goals/resolver.ts — fgca/resolver.ts predates this
+ * module and keeps its own copies). Each resolver assembles a flat document
+ * from a canon element store filtered by a view_config.scope block; these
+ * helpers are the parts that don't vary by notation.
+ */
+export function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** A non-empty string, trimmed. */
+export function str(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const t = v.trim();
+    return t.length > 0 ? t : undefined;
+}
+export function strArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string' && x.trim().length > 0);
+}
+/** `rootId` and every element reachable by following `parent` links downward,
+ *  per the element map's own `parent` field. Used to scope a projection to a
+ *  root element and its transitive descendants (WBS / goal hierarchy / etc). */
+export function descendantsOf(rootId, all) {
+    const childrenByParent = new Map();
+    for (const [id, el] of all) {
+        const parent = str(el['parent']);
+        if (!parent)
+            continue;
+        const list = childrenByParent.get(parent) ?? [];
+        list.push(id);
+        childrenByParent.set(parent, list);
+    }
+    const result = new Set();
+    const queue = [rootId];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (result.has(id))
+            continue;
+        result.add(id);
+        for (const child of childrenByParent.get(id) ?? [])
+            queue.push(child);
+    }
+    return result;
+}
+/** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
+ *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
+ *  memoized across calls via the shared `memo` map. */
+export function parentChainDepth(id, all, memo = new Map(), visiting = new Set()) {
+    const cached = memo.get(id);
+    if (cached !== undefined)
+        return cached;
+    if (visiting.has(id)) {
+        memo.set(id, 0);
+        return 0;
+    }
+    const el = all.get(id);
+    const parent = el ? str(el['parent']) : undefined;
+    if (!parent || !all.has(parent)) {
+        memo.set(id, 0);
+        return 0;
+    }
+    visiting.add(id);
+    const level = parentChainDepth(parent, all, memo, visiting) + 1;
+    visiting.delete(id);
+    memo.set(id, level);
+    return level;
+}
+/** The admission/lifecycle envelope fields (CONTRACT.md §6-7) every canon
+ *  element carries but that carry no rendering/validation meaning once
+ *  projected into a flat notation-specific document. */
+const ENVELOPE_FIELDS = ['notation', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from', 'valid_to'];
+/** `el` with the admission/lifecycle envelope fields removed. */
+export function stripEnvelope(el) {
+    const rest = { ...el };
+    for (const field of ENVELOPE_FIELDS)
+        delete rest[field];
+    return rest;
+}

package/dist/fgca/resolver.js

@@ -66,7 +66,11 @@ export function resolveFGCA(viewDoc, sources) {
     const factorElems = new Map([...factorElemsLegacy, ...factorElemsNew]);
     const goalElems = collectByNotation(sources.elements, 'goal');
     const changeElems = collectByNotation(sources.elements, 'change');
-    const activityElems = collectByNotation(sources.elements, 'activity');
+    // `action` is canonical since methodology 1.0; `activity` is the deprecated
+    // pre-rename alias, still accepted (elements/24-action.md §"Deprecated alias").
+    const activityElemsLegacy = collectByNotation(sources.elements, 'activity');
+    const activityElemsNew = collectByNotation(sources.elements, 'action');
+    const activityElems = new Map([...activityElemsLegacy, ...activityElemsNew]);
     // 1. Select goal set
     const goalsFilter = str(goalsConf['filter']) ?? 'all';
     let selectedGoals;

package/dist/goals/index.d.ts

@@ -2,6 +2,8 @@ export type { Goal, GoalType, GoalTree, ImpactType, ValidationResult, Validation
 export { validateGoalTree } from './validate.js';
 export { parseCanonicalGoals } from './parse-canonical.js';
 export type { CanonicalGoalsResult } from './parse-canonical.js';
+export { resolveGoals, isGoalsViewDoc } from './resolver.js';
+export type { GoalsViewConfig, GoalsCanonSources } from './resolver.js';
 export { layoutGoalTree, selectScopedGoals } from './layout.js';
 export { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';
 export { GoalTreeView } from './GoalTreeView.js';

package/dist/goals/index.js

@@ -1,5 +1,6 @@
 export { validateGoalTree } from './validate.js';
 export { parseCanonicalGoals } from './parse-canonical.js';
+export { resolveGoals, isGoalsViewDoc } from './resolver.js';
 export { layoutGoalTree, selectScopedGoals } from './layout.js';
 export { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';
 export { GoalTreeView } from './GoalTreeView.js';

package/dist/goals/resolver.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Goals Tree canon resolver — assembles a flat canonical Goals document from
+ * a view_config projection and a canon element store (methodology
+ * `notations/views/04-goals.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * and `activities/resolver.ts`'s `resolveAction`/`isActionViewDoc` pattern
+ * for the `goals` notation.
+ *
+ * Output shape matches the flat inline form `parseCanonicalGoals` expects:
+ * top-level `goal_types[]` + `goals[]`. Filesystem-free — callable from unit
+ * tests without vscode.
+ *
+ * `goal_types[]` synthesis: when `view_config.goal_types` is present it is
+ * used as-is (the documented projection-form shape always includes it) and
+ * each goal keeps its own authored `level`, validated against that table as
+ * usual. When absent, §5.2 says the renderer "infers levels from the parent
+ * chain depth (root goals at 0, each step deeper adds 1)" — this resolver
+ * implements that literally (`parentChainDepth`), overriding each selected
+ * goal's `level` with its structural depth, rather than trusting the
+ * element's own stored `level` field. A stored `level` can't be trusted here:
+ * nothing enforces cross-element consistency on it (ELEMENT_PRIMITIVES.md
+ * §7.2: `type`/`level` are independent, both-optional per-element fields),
+ * and worse, using it made the synthesized table's chosen level depend on
+ * which element the canon loader happened to enumerate first — the CLI
+ * (`readdirSync`, unsorted) and the VS Code preview
+ * (`vscode.workspace.fs.readDirectory`, unsorted) can enumerate the same
+ * canon store in different orders, so the two surfaces could disagree on
+ * `GOALS-008` findings for identical input. Structural depth has no such
+ * dependency. A goal with no `type` still surfaces as a genuine `GOALS-006`
+ * finding — this resolver never synthesizes a type label to paper over one.
+ */
+export interface GoalsViewConfig {
+    scope?: {
+        root_goal?: string | null;
+        period?: string | null;
+        type_filter?: string[] | null;
+        valid_at?: string | null;
+    };
+    goal_types?: Array<{
+        name: string;
+        level: number;
+    }>;
+    display?: {
+        depth?: number | null;
+        collapsed?: string[];
+    };
+}
+export interface GoalsCanonSources {
+    elements: unknown[];
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `goals[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `parseCanonicalGoals` on the inline document.
+ */
+export declare function isGoalsViewDoc(parsed: unknown): boolean;
+/**
+ * Assemble a flat canonical Goals document from the canon GOAL element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `parseCanonicalGoals`.
+ */
+export declare function resolveGoals(viewDoc: unknown, sources: GoalsCanonSources): Record<string, unknown>;

package/dist/goals/resolver.js

@@ -0,0 +1,154 @@
+/**
+ * Goals Tree canon resolver — assembles a flat canonical Goals document from
+ * a view_config projection and a canon element store (methodology
+ * `notations/views/04-goals.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * and `activities/resolver.ts`'s `resolveAction`/`isActionViewDoc` pattern
+ * for the `goals` notation.
+ *
+ * Output shape matches the flat inline form `parseCanonicalGoals` expects:
+ * top-level `goal_types[]` + `goals[]`. Filesystem-free — callable from unit
+ * tests without vscode.
+ *
+ * `goal_types[]` synthesis: when `view_config.goal_types` is present it is
+ * used as-is (the documented projection-form shape always includes it) and
+ * each goal keeps its own authored `level`, validated against that table as
+ * usual. When absent, §5.2 says the renderer "infers levels from the parent
+ * chain depth (root goals at 0, each step deeper adds 1)" — this resolver
+ * implements that literally (`parentChainDepth`), overriding each selected
+ * goal's `level` with its structural depth, rather than trusting the
+ * element's own stored `level` field. A stored `level` can't be trusted here:
+ * nothing enforces cross-element consistency on it (ELEMENT_PRIMITIVES.md
+ * §7.2: `type`/`level` are independent, both-optional per-element fields),
+ * and worse, using it made the synthesized table's chosen level depend on
+ * which element the canon loader happened to enumerate first — the CLI
+ * (`readdirSync`, unsorted) and the VS Code preview
+ * (`vscode.workspace.fs.readDirectory`, unsorted) can enumerate the same
+ * canon store in different orders, so the two surfaces could disagree on
+ * `GOALS-008` findings for identical input. Structural depth has no such
+ * dependency. A goal with no `type` still surfaces as a genuine `GOALS-006`
+ * finding — this resolver never synthesizes a type label to paper over one.
+ */
+import { isObject, str, strArray, descendantsOf, parentChainDepth, stripEnvelope } from '../canon-resolver-utils.js';
+/** GOAL elements by id (`notation: goal`). */
+function collectGoalElements(docs) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isObject(doc))
+            continue;
+        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
+    }
+    return out;
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `goals[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `parseCanonicalGoals` on the inline document.
+ */
+export function isGoalsViewDoc(parsed) {
+    if (!isObject(parsed))
+        return false;
+    return 'view_config' in parsed && !('goals' in parsed);
+}
+/**
+ * Assemble a flat canonical Goals document from the canon GOAL element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `parseCanonicalGoals`.
+ */
+export function resolveGoals(viewDoc, sources) {
+    if (!isObject(viewDoc)) {
+        return { notation: 'goals', goal_types: [], goals: [] };
+    }
+    const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
+    const scope = isObject(vc['scope']) ? vc['scope'] : {};
+    const allGoals = collectGoalElements(sources.elements);
+    // 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']);
+    let candidateIds;
+    if (rootGoal) {
+        candidateIds = allGoals.has(rootGoal) ? descendantsOf(rootGoal, allGoals) : new Set();
+    }
+    else {
+        candidateIds = new Set(allGoals.keys());
+    }
+    // 2. Narrow by period — matched against the element's own `period` field
+    // when present (the GOAL element schema, ELEMENT_PRIMITIVES.md §7.2, does
+    // not define this field explicitly; treated as a forward-compatible tag).
+    const period = str(scope['period']);
+    if (period) {
+        candidateIds = new Set([...candidateIds].filter((id) => str(allGoals.get(id)?.['period']) === period));
+    }
+    // 3. Narrow by type_filter — only goals of a listed type.
+    const typeFilter = strArray(scope['type_filter']);
+    if (typeFilter.length > 0) {
+        candidateIds = new Set([...candidateIds].filter((id) => {
+            const t = str(allGoals.get(id)?.['type']);
+            return t !== undefined && typeFilter.includes(t);
+        }));
+    }
+    // 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);
+            const from = str(el?.['valid_from']);
+            const to = str(el?.['valid_to']);
+            if (from && validAt < from)
+                return false;
+            if (to && validAt > to)
+                return false;
+            return true;
+        }));
+    }
+    const explicitGoalTypes = Array.isArray(vc['goal_types'])
+        ? vc['goal_types'].filter(isObject)
+        : undefined;
+    // Element fields map onto Goal fields unchanged — the admission/lifecycle
+    // envelope fields carry no rendering meaning for `parseCanonicalGoals` and
+    // are dropped.
+    let selectedGoals;
+    let goalTypes;
+    if (explicitGoalTypes) {
+        // Main-line case: goals keep their own authored `level`, validated
+        // against the explicit table by parseCanonicalGoals as usual.
+        selectedGoals = [...candidateIds].map((id) => ({ ...stripEnvelope(allGoals.get(id)), id }));
+        goalTypes = explicitGoalTypes;
+    }
+    else {
+        // §5.2 fallback: level is the goal's structural depth in the parent
+        // chain, not its (untrustworthy, order-dependent) stored `level` field.
+        const depthMemo = new Map();
+        selectedGoals = [...candidateIds].map((id) => {
+            const { level: _level, ...rest } = stripEnvelope(allGoals.get(id));
+            return { ...rest, id, level: parentChainDepth(id, allGoals, depthMemo) };
+        });
+        const seen = new Map();
+        for (const g of selectedGoals) {
+            const name = typeof g['type'] === 'string' ? g['type'] : undefined;
+            if (name !== undefined && !seen.has(name)) {
+                seen.set(name, g['level']);
+            }
+        }
+        goalTypes = [...seen.entries()].map(([name, level]) => ({ name, level }));
+    }
+    return {
+        notation: 'goals',
+        id: viewDoc['id'],
+        name: viewDoc['name'],
+        spec_version: viewDoc['spec_version'],
+        description: viewDoc['description'],
+        period: viewDoc['period'],
+        goal_types: goalTypes,
+        goals: selectedGoals,
+    };
+}

package/dist/repo-validate/index.d.ts

@@ -1,2 +1,3 @@
 export { validateRepoModel } from './validate-repo.js';
-export type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+export { resolveRepoModel } from './resolve-model.js';
+export type { RepoDoc, RepoFinding, RepoModelInput, ResolvedElementRecord, ResolvedRelationRecord, ResolvedRepoModel } from './types.js';

package/dist/repo-validate/index.js

@@ -1 +1,2 @@
 export { validateRepoModel } from './validate-repo.js';
+export { resolveRepoModel } from './resolve-model.js';

package/dist/repo-validate/resolve-model.d.ts

@@ -0,0 +1,5 @@
+import type { RepoModelInput, ResolvedRepoModel } from './types.js';
+/** Project a loaded canon model into the resolved element/relation records a
+ *  non-JS consumer can read directly, without depending on this repo's YAML
+ *  parsing internals. Pure: no IO. */
+export declare function resolveRepoModel(input: RepoModelInput): ResolvedRepoModel;