@transitrix/diagrams 1.0.0 → 1.0.1

package/dist/compliance/impact.js

@@ -16,9 +16,9 @@ import { buildComplianceIndex } from './reverse-index.js';
  * are auditable ("what I assumed").
  */
 export const COMPLIANCE_IMPACT_DEFAULTS = {
-    /** Accept all four active statuses + n_a in cell aggregation. */
+    /** Accept all active statuses + n_a in cell aggregation. */
     status_display: {
-        show: ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a'],
+        show: ['compliant', 'partial', 'non_compliant', 'under_review', 'pending_owner', 'n_a'],
     },
     /** Order rows by canonical REQUIREMENT ID (lexicographic). */
     order_rows_by: 'id',
@@ -30,9 +30,9 @@ export const COMPLIANCE_IMPACT_DEFAULTS = {
     /** Obligation scope: all known REQUIREMENTs in the canon (no filter). */
     obligations: { include: undefined, filter: undefined },
     /** Subjects: empty — must be supplied explicitly in the view config. */
-    subjects: { products: [], processes: [] },
-    /** Column grain: one column per business object (no stage decomposition). */
-    grouping: { columns: 'object' },
+    subjects: { products: [], processes: [], capabilities: [] },
+    /** Column grain: one column per subject (no stage/task decomposition). */
+    grouping: { columns: 'product' },
 };
 /**
  * Validate and normalise a raw (YAML-parsed) value into an ImpactViewConfig.
@@ -81,6 +81,16 @@ export function parseImpactViewConfig(raw) {
     const emptyCells = v.empty_cells && typeof v.empty_cells === 'object' && !Array.isArray(v.empty_cells)
         ? v.empty_cells
         : {};
+    // Parse grouping.columns — accept spec-canonical values plus backward-compat aliases.
+    const rawGrouping = v.grouping && typeof v.grouping === 'object' && !Array.isArray(v.grouping)
+        ? v.grouping
+        : null;
+    const rawColumns = typeof rawGrouping?.columns === 'string' ? rawGrouping.columns : undefined;
+    const VALID_COLUMNS = new Set(['product', 'product-stage', 'product-stage-task']);
+    const normalizedColumns = rawColumns === 'object-details' ? 'product-stage' // backward-compat alias
+        : rawColumns === 'object' ? 'product' // backward-compat alias
+            : VALID_COLUMNS.has(rawColumns ?? '') ? rawColumns
+                : undefined;
     const config = {
         id: v.id,
         name: v.name,
@@ -93,6 +103,9 @@ export function parseImpactViewConfig(raw) {
             processes: Array.isArray(subjects.processes)
                 ? subjects.processes.filter((x) => typeof x === 'string')
                 : [...COMPLIANCE_IMPACT_DEFAULTS.subjects.processes],
+            capabilities: Array.isArray(subjects.capabilities)
+                ? subjects.capabilities.filter((x) => typeof x === 'string')
+                : [...COMPLIANCE_IMPACT_DEFAULTS.subjects.capabilities],
         },
         obligations: {
             include: Array.isArray(obligations.include)
@@ -120,6 +133,7 @@ export function parseImpactViewConfig(raw) {
                 : COMPLIANCE_IMPACT_DEFAULTS.empty_cells.no_obligation_applies_label,
         },
         order_rows_by: v.order_rows_by === 'name' ? 'name' : COMPLIANCE_IMPACT_DEFAULTS.order_rows_by,
+        grouping: normalizedColumns !== undefined ? { columns: normalizedColumns } : undefined,
     };
     return { ok: true, config };
 }
@@ -182,9 +196,11 @@ function orderRows(rows, key) {
     return sorted;
 }
 /** Aggregate multiple matching assertions into one cell value, per §5.2 step 4.
+ *  Precedence: non_compliant > partial > pending_owner > under_review > compliant > n_a.
  *  Assumes at least one assertion matches an allowed status; caller filters. */
 function aggregateStatus(assertions) {
     let sawPartial = false;
+    let sawPendingOwner = false;
     let sawUnderReview = false;
     let sawCompliant = false;
     for (const a of assertions) {
@@ -192,6 +208,8 @@ function aggregateStatus(assertions) {
             return 'non_compliant';
         if (a.status === 'partial')
             sawPartial = true;
+        else if (a.status === 'pending_owner')
+            sawPendingOwner = true;
         else if (a.status === 'under_review')
             sawUnderReview = true;
         else if (a.status === 'compliant')
@@ -199,6 +217,8 @@ function aggregateStatus(assertions) {
     }
     if (sawPartial)
         return 'partial';
+    if (sawPendingOwner)
+        return 'pending_owner';
     if (sawUnderReview)
         return 'under_review';
     if (sawCompliant)
@@ -206,13 +226,22 @@ function aggregateStatus(assertions) {
     return 'n_a';
 }
 // ── Column builder helpers (CV-3a) ──────────────────────────────────────────
-function buildProductColumns(config) {
-    const subjects = [...(config.subjects.products ?? []), ...(config.subjects.processes ?? [])];
-    return subjects.map(id => ({ subjectId: id, label: id }));
+function buildProductColumns(config, namedItems) {
+    const nameMap = new Map(namedItems.map(p => [p.id, p.name]));
+    const subjects = [
+        ...(config.subjects.products ?? []),
+        ...(config.subjects.processes ?? []),
+        ...(config.subjects.capabilities ?? []),
+    ];
+    return subjects.map(id => ({ subjectId: id, label: id, subjectName: nameMap.get(id) }));
 }
 function buildObjectDetailColumns(config, objectDetails) {
     const detailMap = new Map(objectDetails.map(d => [d.objectId, d.details]));
-    const subjects = [...(config.subjects.products ?? []), ...(config.subjects.processes ?? [])];
+    const subjects = [
+        ...(config.subjects.products ?? []),
+        ...(config.subjects.processes ?? []),
+        ...(config.subjects.capabilities ?? []),
+    ];
     const cols = [];
     for (const subjectId of subjects) {
         const details = detailMap.get(subjectId);
@@ -227,13 +256,57 @@ function buildObjectDetailColumns(config, objectDetails) {
     }
     return cols;
 }
+/**
+ * Build `product-stage-task` columns: one column per (subject, stage, task) triple.
+ * Each stage in `objectDetails` that carries a `tasks[]` array is expanded to
+ * per-task columns `{ subjectId, stageId, taskId, label: subjectId:stageId:taskId }`.
+ * Stages with no tasks fall back to a single stage-grain column.
+ */
+function buildTaskColumns(config, objectDetails) {
+    const detailMap = new Map(objectDetails.map(d => [d.objectId, d.details]));
+    const subjects = [
+        ...(config.subjects.products ?? []),
+        ...(config.subjects.processes ?? []),
+        ...(config.subjects.capabilities ?? []),
+    ];
+    const cols = [];
+    for (const subjectId of subjects) {
+        const stages = detailMap.get(subjectId);
+        if (!stages || stages.length === 0) {
+            cols.push({ subjectId, label: subjectId });
+        }
+        else {
+            for (const stage of stages) {
+                if (!stage.tasks || stage.tasks.length === 0) {
+                    // Stage with no tasks: fall back to stage-grain column.
+                    cols.push({ subjectId, stageId: stage.id, label: `${subjectId}:${stage.id}` });
+                }
+                else {
+                    for (const task of stage.tasks) {
+                        cols.push({
+                            subjectId,
+                            stageId: stage.id,
+                            taskId: task.id,
+                            label: `${subjectId}:${stage.id}:${task.id}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return cols;
+}
 /**
  * Returns true when assertion `a` contributes to column `col`.
  *
  * At `'product'` grain: `a.subject` must match `col.subjectId`.
  * At `'product-stage'` grain: `a.subject` must match AND either
- * `a.realised_via` is absent (claim covers the whole subject, so every stage
- * inherits it) OR `col.stageId` ∈ `a.realised_via`.
+ * `a.realised_via` is absent (claim covers the whole subject) OR
+ * `col.stageId` ∈ `a.realised_via`.
+ * At `'product-stage-task'` grain: as above for stage, plus `col.taskId` ∈
+ * `a.realised_via` counts as a match (task-level claim covers this task column).
+ * A stage-level claim (`col.stageId` ∈ `a.realised_via`) covers all task columns
+ * in that stage.
  */
 function assertionMatchesColumn(a, col) {
     if (a.subject !== col.subjectId)
@@ -242,19 +315,30 @@ function assertionMatchesColumn(a, col) {
         return true;
     if (!a.realised_via || a.realised_via.length === 0)
         return true;
+    if (col.taskId) {
+        // Task grain: match on taskId OR on stageId (stage claim covers all tasks).
+        return a.realised_via.includes(col.taskId) || a.realised_via.includes(col.stageId);
+    }
     return a.realised_via.includes(col.stageId);
 }
 /**
  * Build the matrix per §5.2.
  *
  * At the default `grouping.columns: 'product'` grain, one column per subject.
- * At `grouping.columns: 'product-stage'`, pass `objectDetails` to expand each
- * subject into per-stage sub-columns (typically extracted from a
- * process-blueprint document via `extractObjectDetails`).  Subjects with no
- * stage mapping fall back to a single product-grain column automatically.
  *
- * Subjects are taken from `config.subjects.products` and
- * `config.subjects.processes` (in that order).  Subjects with no binding
+ * At `grouping.columns: 'product-stage'`, pass `objectDetails` (from
+ * `extractObjectDetails` on a process-blueprint) to expand each subject into
+ * per-stage sub-columns.  Subjects with no stage mapping fall back to a single
+ * product-grain column.
+ *
+ * At `grouping.columns: 'product-stage-task'`, pass `objectDetails` where each
+ * stage carries a `tasks[]` array (combine blueprint stages and process-flow
+ * tasks via `mergeStageTaskDetails`).  Each task becomes a
+ * `(subject, stage, task)` column.  Stages with no tasks fall back to
+ * stage-grain columns.
+ *
+ * Subjects are taken from `config.subjects.products`, `config.subjects.processes`,
+ * and `config.subjects.capabilities` (in that order).  Subjects with no binding
  * obligation still appear as columns so the gap is visible.
  */
 export function buildImpactMatrix(canon, config, objectDetails) {
@@ -263,11 +347,14 @@ export function buildImpactMatrix(canon, config, objectDetails) {
         assertions: canon.assertions,
     });
     const obligations = orderRows(resolveObligations(config, index, canon.requirements), config.order_rows_by);
-    const useStageGrain = config.grouping?.columns === 'object-details' && objectDetails && objectDetails.length > 0;
-    const columns = useStageGrain
-        ? buildObjectDetailColumns(config, objectDetails)
-        : buildProductColumns(config);
-    const allowedStatuses = new Set(config.status_display?.show ?? ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']);
+    const grain = config.grouping?.columns ?? 'product';
+    const hasDetails = objectDetails !== undefined && objectDetails.length > 0;
+    const columns = grain === 'product-stage-task' && hasDetails
+        ? buildTaskColumns(config, objectDetails)
+        : (grain === 'product-stage' || grain === 'object-details') && hasDetails
+            ? buildObjectDetailColumns(config, objectDetails)
+            : buildProductColumns(config, [...(canon.products ?? []), ...(canon.subjects ?? [])]);
+    const allowedStatuses = new Set(config.status_display?.show ?? ['compliant', 'partial', 'non_compliant', 'under_review', 'pending_owner', 'n_a']);
     const rowIndex = new Set(obligations.map(r => r.id));
     const cells = obligations.map(() => columns.map(() => emptyCell()));
     for (let c = 0; c < columns.length; c++) {
@@ -357,9 +444,10 @@ function emptyCell() {
         decoration: { isNew: false, isUrgent: false, deadlineStatus: 'none' },
     };
 }
-// ── Process-blueprint stage extractor (CV-3a) ───────────────────────────────
+// ── Process-blueprint / process-flow extractors (CV-3a) ─────────────────────
 /**
- * Extract `ObjectDetailInput` from a raw (YAML-parsed) process-blueprint document.
+ * Extract stage-level `ObjectDetailInput` from a raw (YAML-parsed)
+ * process-blueprint document.
  *
  * Accepts both the bare document object and the wrapped form
  * (`{ process_blueprint: { id, stages: […] } }`).
@@ -368,6 +456,8 @@ function emptyCell() {
  *
  * Pass the returned value into `buildImpactMatrix` as part of the
  * `objectDetails` array when `grouping.columns: 'product-stage'` is configured.
+ * For `grouping.columns: 'product-stage-task'`, combine with
+ * `extractProcessFlowTasks` via `mergeStageTaskDetails`.
  */
 export function extractObjectDetails(doc) {
     if (!doc || typeof doc !== 'object' || Array.isArray(doc))
@@ -396,12 +486,90 @@ export function extractObjectDetails(doc) {
     }
     return { objectId: id, details };
 }
+/**
+ * Extract task-type steps from a raw (YAML-parsed) PROCESS element document.
+ *
+ * Reads `notation: process` documents with an inline `flow.steps[]` array.
+ * Filters for task-type nodes (`task`, `userTask`, `serviceTask`) — start/end
+ * events and gateways are excluded.  Returns a flat `ObjectDetailInput` where
+ * `details` are the extracted task steps in declaration order.
+ *
+ * Returns `null` when the document is not a recognisable process element or
+ * has no `id` / `flow.steps` array.
+ *
+ * Use the returned value with `mergeStageTaskDetails` to embed tasks into
+ * blueprint stages for `grouping.columns: product-stage-task`.
+ */
+export function extractProcessFlowTasks(doc) {
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return null;
+    const top = doc;
+    if (top.notation !== 'process')
+        return null;
+    const id = typeof top.id === 'string' ? top.id : null;
+    if (!id)
+        return null;
+    const flow = top.flow && typeof top.flow === 'object' && !Array.isArray(top.flow)
+        ? top.flow
+        : null;
+    if (!flow || !Array.isArray(flow.steps))
+        return null;
+    const TASK_TYPES = new Set(['task', 'userTask', 'serviceTask', 'scriptTask',
+        'receiveTask', 'sendTask', 'manualTask', 'businessRuleTask', 'callActivity', 'subProcess']);
+    const details = [];
+    for (const step of flow.steps) {
+        if (!step || typeof step !== 'object' || Array.isArray(step))
+            continue;
+        const s = step;
+        const stepId = typeof s.id === 'string' ? s.id : null;
+        if (!stepId)
+            continue;
+        if (!TASK_TYPES.has(s.type))
+            continue;
+        details.push({ id: stepId, name: typeof s.name === 'string' ? s.name : stepId });
+    }
+    return details.length > 0 ? { objectId: id, details } : null;
+}
+/**
+ * Combine blueprint stage details (from `extractObjectDetails`) with
+ * process-flow task details (from `extractProcessFlowTasks`) into a
+ * stage-with-tasks hierarchy for `grouping.columns: product-stage-task`.
+ *
+ * All tasks from `taskInput.details` are distributed into their parent stage
+ * by matching the `stageOwner` map: `stageId → taskId[]`.  If `stageOwner` is
+ * omitted (no stage-to-task mapping is available), all tasks are placed into
+ * every stage (`undefined` key `→` all tasks).
+ *
+ * When `taskInput` is `null` or its `objectId` does not match `stageInput`,
+ * returns `stageInput` unchanged (callers can safely chain the result into
+ * `buildImpactMatrix` — it will degrade to stage-grain columns).
+ *
+ * @param stageInput   Stage-level detail (from `extractObjectDetails`).
+ * @param taskInput    Task-level detail  (from `extractProcessFlowTasks`).
+ * @param stageOwner   Optional mapping `stageId → taskId[]`. When provided,
+ *                     only tasks listed for a stage are embedded in it.
+ */
+export function mergeStageTaskDetails(stageInput, taskInput, stageOwner) {
+    if (!taskInput || taskInput.objectId !== stageInput.objectId)
+        return stageInput;
+    const allTasks = taskInput.details;
+    return {
+        objectId: stageInput.objectId,
+        details: stageInput.details.map(stage => {
+            const stageTasks = stageOwner
+                ? allTasks.filter(t => (stageOwner[stage.id] ?? []).includes(t.id))
+                : allTasks;
+            return stageTasks.length > 0 ? { ...stage, tasks: stageTasks } : stage;
+        }),
+    };
+}
 // ── Markdown rendering ──────────────────────────────────────────────────────
 const STATUS_GLYPH = {
     compliant: 'OK',
     partial: 'PARTIAL',
     non_compliant: 'FAIL',
     under_review: 'REVIEW',
+    pending_owner: 'PENDING',
     n_a: 'N/A',
 };
 function escMd(s) {
@@ -450,7 +618,7 @@ export function renderImpactMarkdown(matrix) {
     lines.push('');
     lines.push('## Legend');
     lines.push('');
-    lines.push('- **OK / PARTIAL / FAIL / REVIEW / N/A** — aggregated `ASSERTION.status` per §5.2.');
+    lines.push('- **OK / PARTIAL / FAIL / REVIEW / PENDING / N/A** — aggregated `ASSERTION.status` per §5.2.');
     lines.push(`- **${escMd(matrix.emptyLabels.no_obligation_label)}** — modelling gap; no admitted ASSERTION binds this (obligation, subject) pair.`);
     lines.push(`- **${escMd(matrix.emptyLabels.no_obligation_applies_label)}** — modelled fact; an admitted ASSERTION with status \`n_a\` excludes this pair.`);
     return lines.join('\n') + '\n';

package/dist/compliance/index.d.ts

@@ -8,9 +8,9 @@ export { renderComplianceMarkdown } from './markdown.js';
 export type { ReportScope, MarkdownOptions } from './markdown.js';
 export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
 export type { HtmlOptions, ImpactMatrixHtmlOptions } from './html.js';
-export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, computeDeadlineStatus } from './impact.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
 export type { ImpactCell, ImpactColumn, ImpactEmptyCellLabels, ImpactGrouping, ImpactMatrix, ImpactObligationFilter, ImpactStatusDisplay, ImpactSubjects, ImpactViewConfig, ParseImpactViewConfigResult, } from './impact.js';
 export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
 export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';
-export type { CoverageMetricConfig, CoverageMetricScope, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.js';
+export type { CoverageMetricConfig, CoverageMetricRegimes, CoverageMetricRegimesFilter, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.js';
 export type { ComplianceIndex, ComplianceIndexInput, DeadlineStatus, IndexRequirement, IndexAssertion, LawTree, LawTreeRequirement, ProductView, ProductRequirementStatus, ObjectDetailDef, ObjectDetailInput, } from './types.js';

package/dist/compliance/index.js

@@ -4,6 +4,6 @@ export { buildGapReport } from './gap-report.js';
 export { emptyCanon, ingestComplianceDoc } from './classify.js';
 export { renderComplianceMarkdown } from './markdown.js';
 export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
-export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, computeDeadlineStatus } from './impact.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
 export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
 export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';

package/dist/compliance/markdown.js

@@ -10,6 +10,7 @@ const STATUS_LABELS = {
     partial: 'Partial',
     non_compliant: 'Non-compliant',
     under_review: 'Under review',
+    pending_owner: 'Pending owner',
     n_a: 'N/A',
 };
 /** Escapes a value for a Markdown table cell (pipes + newlines). */

package/dist/compliance/types.d.ts

@@ -44,18 +44,37 @@ export interface IndexAssertion {
      * stage-grouped matrix cells.
      */
     realised_via?: string[];
+    /** ID or name of the party who must confirm this assertion (pending-owner state). */
+    owner_to_confirm?: string;
 }
-/** One detail-level element of a business object, used as a matrix sub-column. */
+/** One stage (or task) element of a business object, used as a matrix sub-column. */
 export interface ObjectDetailDef {
     id: string;
     name: string;
+    /**
+     * Ordered task-type flow steps within this stage.
+     * Present only when `grouping.columns: product-stage-task` grain is active.
+     * Each task produces a separate matrix column: (subject, stageId, taskId).
+     * When absent or empty, the stage itself is the column grain.
+     */
+    tasks?: Array<{
+        id: string;
+        name: string;
+    }>;
 }
 /**
- * Maps a business object to its ordered detail elements.
- * Passed into `buildImpactMatrix` when `grouping.columns` is
- * `object-details`. The details can be process stages, product
- * components, capability modules, etc. — whatever sub-structure the object
- * exposes. Typically extracted from a process-blueprint via`extractObjectDetails`.
+ * Maps a business object to its ordered stages (and optionally their tasks).
+ * Passed into `buildImpactMatrix` to enable stage/task column grouping.
+ *
+ * - For `grouping.columns: product-stage`: `details` contains stages; each
+ *   stage becomes one matrix column.
+ * - For `grouping.columns: product-stage-task`: each stage in `details` carries
+ *   a `tasks` array; each task produces a `(subject, stage, task)` column.
+ *   Stages with no tasks fall back to a stage-grain column.
+ *
+ * Typically built by combining `extractObjectDetails` (blueprint stages) and
+ * `extractProcessFlowTasks` (process flow tasks), then merging via
+ * `mergeStageTaskDetails`.
  */
 export interface ObjectDetailInput {
     objectId: string;

package/dist/edge-path.d.ts

@@ -10,9 +10,13 @@ export declare const DEFAULT_EDGE_CURVATURE = 1;
  * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
  * (tx,ty).
  *
- * `curvature` scales the control-handle length:
- *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ * `curvature` scales the exit control-handle (departure from source).
+ * `entryCurvature` scales the entry control-handle (arrival at target);
+ * defaults to `curvature` when omitted so callers that pass one value get
+ * symmetric handles (the historical behaviour).
+ *
+ *   - 0   → handle collapses onto its endpoint ⇒ straight at that end.
  *   - 1   → the historical curve (no visual change from before #76).
- *   - >1  → progressively stronger arc.
+ *   - >1  → progressively stronger arc at that end.
  */
-export declare function horizontalCubicEdgePath(sx: number, sy: number, tx: number, ty: number, curvature?: number): string;
+export declare function horizontalCubicEdgePath(sx: number, sy: number, tx: number, ty: number, curvature?: number, entryCurvature?: number): string;

package/dist/edge-path.js

@@ -21,15 +21,20 @@ export const DEFAULT_EDGE_CURVATURE = 1;
  * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
  * (tx,ty).
  *
- * `curvature` scales the control-handle length:
- *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ * `curvature` scales the exit control-handle (departure from source).
+ * `entryCurvature` scales the entry control-handle (arrival at target);
+ * defaults to `curvature` when omitted so callers that pass one value get
+ * symmetric handles (the historical behaviour).
+ *
+ *   - 0   → handle collapses onto its endpoint ⇒ straight at that end.
  *   - 1   → the historical curve (no visual change from before #76).
- *   - >1  → progressively stronger arc.
+ *   - >1  → progressively stronger arc at that end.
  */
-export function horizontalCubicEdgePath(sx, sy, tx, ty, curvature = DEFAULT_EDGE_CURVATURE) {
+export function horizontalCubicEdgePath(sx, sy, tx, ty, curvature = DEFAULT_EDGE_CURVATURE, entryCurvature) {
     const dx = tx - sx;
     const dy = ty - sy;
     const baseHandle = Math.max(EDGE_MIN_HANDLE, Math.abs(dx) * DX_FACTOR, Math.abs(dy) * DY_FACTOR);
-    const handle = baseHandle * curvature;
-    return `M${sx},${sy} C${sx + handle},${sy} ${tx - handle},${ty} ${tx},${ty}`;
+    const exitHandle = baseHandle * curvature;
+    const entryHandle = baseHandle * (entryCurvature ?? curvature);
+    return `M${sx},${sy} C${sx + exitHandle},${sy} ${tx - entryHandle},${ty} ${tx},${ty}`;
 }

package/dist/factor/__tests__/validate.test.js

@@ -1,10 +1,10 @@
 import { describe, it, expect } from 'vitest';
 import { validateFactor } from '../validate.js';
-function valid() {
+function validExternal() {
     return {
         notation: 'factor',
         id: 'FACTOR-EU-REG-1',
-        name: 'EU regulatory window for market entry',
+        name: 'EU regulatory window',
         type: 'external',
         category: 'legal',
         description: 'Standing external driver — the EU regulatory regime.',
@@ -17,67 +17,96 @@ function valid() {
         valid_to: null,
     };
 }
-const codes = (input) => validateFactor(input).errors.map(e => e.code);
-const warns = (input) => validateFactor(input).warnings.map(w => w.code);
+function validInternal() {
+    return {
+        notation: 'factor',
+        id: 'FACTOR-COMP-1',
+        name: 'Support response time',
+        type: 'internal',
+        description: 'Standing internal driver.',
+        zone: 'canon',
+        admitted_at: '2026-05-29',
+        admitted_by: 'v.korobeinikov',
+        gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+        valid_from: '2026-05-26',
+        valid_to: null,
+    };
+}
+const codes = (input, opts) => validateFactor(input, opts).errors.map(e => e.code);
 describe('validateFactor — positive', () => {
-    it('accepts the worked-example FACTOR-EU-REG-1', () => {
-        const r = validateFactor(valid());
+    it('accepts a well-formed external PESTLE factor', () => {
+        const r = validateFactor(validExternal());
         expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-        expect(r.errors).toHaveLength(0);
     });
-    it('accepts a minimal factor (no type/category/references)', () => {
-        const r = valid();
-        delete r.type;
-        delete r.category;
-        delete r.references_constraint;
-        expect(validateFactor(r).valid).toBe(true);
+    it('accepts a well-formed internal factor (no PESTLE category)', () => {
+        expect(validateFactor(validInternal()).valid).toBe(true);
     });
-});
-describe('validateFactor — FACTOR-001 (envelope / shape)', () => {
-    it('flags a non-object', () => {
-        expect(codes(null)).toEqual(['FACTOR-001']);
-        expect(codes(['x'])).toEqual(['FACTOR-001']);
+    it('accepts a minimal factor with no optional fields', () => {
+        const f = validInternal();
+        delete f.type;
+        delete f.description;
+        expect(validateFactor(f).valid).toBe(true);
     });
-    it('flags a wrong notation tag', () => {
-        expect(codes({ ...valid(), notation: 'driver' })).toContain('FACTOR-001');
+});
+describe('validateFactor — FACTOR-001 (shape / id grammar)', () => {
+    it('flags a missing required envelope field', () => {
+        const f = validExternal();
+        delete f.admitted_by;
+        expect(codes(f)).toContain('FACTOR-001');
     });
-    it('flags an id with the wrong TYPE prefix', () => {
-        expect(codes({ ...valid(), id: 'GOAL-EU-1' })).toContain('FACTOR-001');
+    it('flags an id that violates the grammar', () => {
+        expect(codes({ ...validExternal(), id: 'FACTOR-EU-REG-001' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), id: 'FAC-1' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), id: 'factor-1' })).toContain('FACTOR-001');
     });
-    it('flags an id with a leading-zero terminal', () => {
-        expect(codes({ ...valid(), id: 'FACTOR-EU-REG-01' })).toContain('FACTOR-001');
+    it('flags a wrong notation tag and a non-canon zone', () => {
+        expect(codes({ ...validExternal(), notation: 'driver' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), zone: 'sandbox' })).toContain('FACTOR-001');
     });
     it('flags a missing valid_to key (distinct from a null value)', () => {
-        const r = valid();
-        delete r.valid_to;
-        expect(codes(r)).toContain('FACTOR-001');
-        expect(validateFactor({ ...valid(), valid_to: null }).valid).toBe(true);
+        const f = validExternal();
+        delete f.valid_to;
+        expect(codes(f)).toContain('FACTOR-001');
     });
-    it('flags references_constraint entries that are not CONSTRAINT typed ids', () => {
-        expect(codes({ ...valid(), references_constraint: ['GOAL-EU-1'] })).toContain('FACTOR-001');
-        expect(codes({ ...valid(), references_constraint: 'CONSTRAINT-X-1' })).toContain('FACTOR-001');
+    it('rejects a non-object', () => {
+        expect(codes(null)).toEqual(['FACTOR-001']);
+        expect(codes(['a'])).toEqual(['FACTOR-001']);
     });
 });
 describe('validateFactor — FACTOR-002 (type enum)', () => {
-    it('flags a type outside external/internal', () => {
-        expect(codes({ ...valid(), type: 'driver' })).toContain('FACTOR-002');
-    });
-    it('accepts each permitted type', () => {
-        for (const t of ['external', 'internal']) {
-            expect(codes({ ...valid(), type: t, category: undefined })).not.toContain('FACTOR-002');
-        }
+    it('flags a type value outside {external, internal}', () => {
+        expect(codes({ ...validExternal(), type: 'driver' })).toContain('FACTOR-002');
     });
 });
 describe('validateFactor — FACTOR-003 (PESTLE category)', () => {
-    it('flags a category outside the PESTLE classes', () => {
-        expect(codes({ ...valid(), category: 'cultural' })).toContain('FACTOR-003');
+    it('flags a category outside PESTLE', () => {
+        expect(codes({ ...validExternal(), category: 'cosmic' })).toContain('FACTOR-003');
     });
-    it('warns when category is set on an internal factor', () => {
-        expect(warns({ ...valid(), type: 'internal', category: 'economic' })).toContain('FACTOR-003');
+    it('flags PESTLE category on an internal factor', () => {
+        const f = validInternal();
+        f.category = 'legal';
+        expect(codes(f)).toContain('FACTOR-003');
     });
-    it('accepts each permitted PESTLE class', () => {
-        for (const c of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
-            expect(codes({ ...valid(), category: c })).not.toContain('FACTOR-003');
+    it('accepts each permitted PESTLE category on an external factor', () => {
+        for (const cat of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
+            const f = validExternal();
+            f.category = cat;
+            expect(codes(f)).not.toContain('FACTOR-003');
         }
     });
 });
+describe('validateFactor — FACTOR-004 (references_constraint)', () => {
+    it('flags a malformed references_constraint entry', () => {
+        expect(codes({ ...validExternal(), references_constraint: ['not an id'] })).toContain('FACTOR-004');
+    });
+    it('flags a references_constraint entry of the wrong TYPE', () => {
+        expect(codes({ ...validExternal(), references_constraint: ['GOAL-X-1'] })).toContain('FACTOR-004');
+    });
+    it('flags an unresolved id when a catalog is supplied', () => {
+        const catalog = { typeOf: () => undefined };
+        expect(codes(validExternal(), { catalog })).toContain('FACTOR-004');
+    });
+    it('does not flag without a catalog for a well-formed CONSTRAINT id', () => {
+        expect(codes(validExternal())).not.toContain('FACTOR-004');
+    });
+});

package/dist/factor/index.d.ts

@@ -1,3 +1,4 @@
-export type { Factor as FactorPrimitive, FactorType, FactorCategory } from './types.js';
-export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export type { Factor, FactorType, FactorPestleCategory } from './types.js';
+export { FACTOR_PESTLE_CATEGORIES } from './types.js';
 export { validateFactor } from './validate.js';
+export type { FactorValidateOptions } from './validate.js';

package/dist/factor/index.js

@@ -1,2 +1,2 @@
-export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export { FACTOR_PESTLE_CATEGORIES } from './types.js';
 export { validateFactor } from './validate.js';