@transitrix/diagrams 1.5.0 → 1.7.6

package/dist/capability-map/dsm-schema.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Types for the DSM-migration capability map (docs/extraction/capability-map.md).
+ *
+ * Distinct from `./types.ts` (`CapabilityNode`/`CapabilityMapFile`), which is
+ * Transitrix's own native `*.capability-map.transitrix.yaml` notation — a
+ * nested-children tree, statically rendered to SVG. This module is a
+ * separate, flat, address-triple data model matching DSM's internal
+ * capability editor, for the interactive `CapabilityMapView` component. The
+ * two coexist in this folder by design (see the address-helper/component
+ * deliverables in the extraction spec); only the validator function name
+ * collided, so it's `validateCapabilityMapData` here, not
+ * `validateCapabilityMap` (already taken by `./validate.ts`).
+ */
+export interface MaturitySnapshot {
+    date: string;
+    level: number;
+}
+export interface Capability {
+    id: number;
+    name: string;
+    /** 'X.Y.Z' triple. X=0 or backlog=true means "not on the diagram". */
+    address: string;
+    backlog?: boolean;
+    description?: string;
+    maturity?: MaturitySnapshot[];
+}
+export interface CapabilityMap {
+    organisation: string;
+    set_id: string;
+    capabilities: Capability[];
+}
+export type { ValidationError, ValidationWarning, ValidationResult, } from '../validation-types.js';
+import type { ValidationError } from '../validation-types.js';
+export interface MutationResult<T> {
+    ok: boolean;
+    result?: T;
+    error?: ValidationError;
+}
+export interface LayoutOptions {
+    rankdir?: 'LR' | 'TB';
+    nodeWidth?: number;
+    nodeHeight?: number;
+    rankSep?: number;
+    nodeSep?: number;
+    hideCollapsed?: number[];
+    organisationLabel?: string;
+}
+export interface LaidOutNode {
+    id: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: Capability | null;
+    hasHiddenChildren: boolean;
+}
+export interface LaidOutEdge {
+    source: number | 'root';
+    target: number;
+}
+export interface CapabilityMapLayout {
+    rootNode: LaidOutNode;
+    nodes: LaidOutNode[];
+    edges: LaidOutEdge[];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

package/dist/capability-map/dsm-schema.js

@@ -0,0 +1,14 @@
+/**
+ * Types for the DSM-migration capability map (docs/extraction/capability-map.md).
+ *
+ * Distinct from `./types.ts` (`CapabilityNode`/`CapabilityMapFile`), which is
+ * Transitrix's own native `*.capability-map.transitrix.yaml` notation — a
+ * nested-children tree, statically rendered to SVG. This module is a
+ * separate, flat, address-triple data model matching DSM's internal
+ * capability editor, for the interactive `CapabilityMapView` component. The
+ * two coexist in this folder by design (see the address-helper/component
+ * deliverables in the extraction spec); only the validator function name
+ * collided, so it's `validateCapabilityMapData` here, not
+ * `validateCapabilityMap` (already taken by `./validate.ts`).
+ */
+export {};

package/dist/capability-map/dsm-theme.d.ts

@@ -0,0 +1,20 @@
+/** Theme tokens for CapabilityMapView — same host-agnostic-prop pattern as
+ *  the goals module's ThemeTokens (see ../goals/theme.ts). */
+export interface ThemeTokens {
+    cardFill?: string;
+    cardBorderColor?: string;
+    cardBorderWidth?: number;
+    cardTextColor?: string;
+    cardMetaColor?: string;
+    edgeColor?: string;
+    edgeWidth?: number;
+    dropTargetBorderColor?: string;
+    rootFill?: string;
+    rootTextColor?: string;
+}
+/** Default 1..5 maturity-dot colour scale — overridable via the
+ *  `maturityColours` prop (spec §6.2), which is separate from ThemeTokens
+ *  since it's keyed by maturity level, not a fixed named token. */
+export declare const DEFAULT_MATURITY_COLOURS: Record<number, string>;
+export declare const DEFAULT_THEME: Required<ThemeTokens>;
+export declare function resolveTheme(theme?: ThemeTokens): Required<ThemeTokens>;

package/dist/capability-map/dsm-theme.js

@@ -0,0 +1,36 @@
+/** Default 1..5 maturity-dot colour scale — overridable via the
+ *  `maturityColours` prop (spec §6.2), which is separate from ThemeTokens
+ *  since it's keyed by maturity level, not a fixed named token. */
+export const DEFAULT_MATURITY_COLOURS = {
+    1: '#ef4444',
+    2: '#f97316',
+    3: '#eab308',
+    4: '#84cc16',
+    5: '#22c55e',
+};
+export const DEFAULT_THEME = {
+    cardFill: '#eff6ff',
+    cardBorderColor: '#94a3b8',
+    cardBorderWidth: 1,
+    cardTextColor: '#0f172a',
+    cardMetaColor: '#64748b',
+    edgeColor: '#94a3b8',
+    edgeWidth: 1.5,
+    dropTargetBorderColor: '#2563eb',
+    rootFill: '#e2e8f0',
+    rootTextColor: '#0f172a',
+};
+export function resolveTheme(theme) {
+    return {
+        cardFill: theme?.cardFill ?? DEFAULT_THEME.cardFill,
+        cardBorderColor: theme?.cardBorderColor ?? DEFAULT_THEME.cardBorderColor,
+        cardBorderWidth: theme?.cardBorderWidth ?? DEFAULT_THEME.cardBorderWidth,
+        cardTextColor: theme?.cardTextColor ?? DEFAULT_THEME.cardTextColor,
+        cardMetaColor: theme?.cardMetaColor ?? DEFAULT_THEME.cardMetaColor,
+        edgeColor: theme?.edgeColor ?? DEFAULT_THEME.edgeColor,
+        edgeWidth: theme?.edgeWidth ?? DEFAULT_THEME.edgeWidth,
+        dropTargetBorderColor: theme?.dropTargetBorderColor ?? DEFAULT_THEME.dropTargetBorderColor,
+        rootFill: theme?.rootFill ?? DEFAULT_THEME.rootFill,
+        rootTextColor: theme?.rootTextColor ?? DEFAULT_THEME.rootTextColor,
+    };
+}

package/dist/capability-map/dsm-validate.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from './dsm-schema.js';
+export declare function validateCapabilityMapData(input: unknown): ValidationResult;

package/dist/capability-map/dsm-validate.js

@@ -0,0 +1,93 @@
+/** Parses an address string loosely enough to tell "wrong shape"
+ *  (INVALID_ADDRESS_FORMAT) apart from "right shape, too many levels"
+ *  (MAX_DEPTH_EXCEEDED, e.g. '1.2.3.4') — a strict 3-segment regex would
+ *  reject both identically and lose that distinction. */
+function parseLoose(address) {
+    const parts = address.trim().split('.');
+    if (parts.length < 3 || !parts.every((p) => /^\d+$/.test(p)))
+        return null;
+    if (parts.length > 3)
+        return { tooDeep: true };
+    return { triple: [Number(parts[0]), Number(parts[1]), Number(parts[2])] };
+}
+export function validateCapabilityMapData(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return { valid: false, errors: [{ code: 'SCHEMA_INVALID', message: 'Input must be an object' }], warnings: [] };
+    }
+    const raw = input;
+    if (!Array.isArray(raw.capabilities)) {
+        errors.push({ code: 'SCHEMA_INVALID', message: 'capabilities must be an array', path: 'capabilities' });
+        return { valid: false, errors, warnings };
+    }
+    const map = raw;
+    const idSet = new Set();
+    const addressToId = new Map();
+    const onDiagram = new Map();
+    for (let i = 0; i < map.capabilities.length; i++) {
+        const c = map.capabilities[i];
+        const path = `capabilities[${i}]`;
+        if (!c || typeof c !== 'object') {
+            errors.push({ code: 'SCHEMA_INVALID', message: 'capability entry must be an object', path });
+            continue;
+        }
+        const cap = c;
+        if (typeof cap.id !== 'number') {
+            errors.push({ code: 'SCHEMA_INVALID', message: 'capability id must be a number', path });
+            continue;
+        }
+        if (idSet.has(cap.id)) {
+            errors.push({ code: 'DUPLICATE_ID', message: `Duplicate capability id: ${cap.id}`, path });
+        }
+        else {
+            idSet.add(cap.id);
+        }
+        if (!cap.name || typeof cap.name !== 'string' || cap.name.trim() === '') {
+            errors.push({ code: 'EMPTY_NAME', message: `Capability ${cap.id} has empty name`, path });
+        }
+        if (typeof cap.address !== 'string') {
+            errors.push({ code: 'INVALID_ADDRESS_FORMAT', message: `Capability ${cap.id} address must be a string`, path });
+            continue;
+        }
+        const parsed = parseLoose(cap.address);
+        if (parsed === null) {
+            errors.push({ code: 'INVALID_ADDRESS_FORMAT', message: `Capability ${cap.id} address "${cap.address}" is not in 'X.Y.Z' form`, path });
+            continue;
+        }
+        if ('tooDeep' in parsed) {
+            errors.push({ code: 'MAX_DEPTH_EXCEEDED', message: `Capability ${cap.id} address "${cap.address}" has more than 3 levels`, path });
+            continue;
+        }
+        const triple = parsed.triple;
+        const isBacklog = cap.backlog === true || triple[0] === 0;
+        if (!isBacklog) {
+            if (addressToId.has(cap.address)) {
+                errors.push({ code: 'DUPLICATE_ADDRESS', message: `Duplicate address "${cap.address}" (capability ${cap.id})`, path });
+            }
+            else {
+                addressToId.set(cap.address, cap.id);
+            }
+            onDiagram.set(cap.id, triple);
+        }
+        if (Array.isArray(cap.maturity)) {
+            for (const snap of cap.maturity) {
+                const level = snap?.level;
+                if (typeof level === 'number' && (level < 1 || level > 5)) {
+                    warnings.push({ code: 'INVALID_MATURITY_LEVEL', message: `Capability ${cap.id} has maturity level ${level} outside 1..5`, path });
+                }
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    for (const [id, [x, y, z]] of onDiagram) {
+        if (z !== 0 && !addressToId.has(`${x}.${y}.0`)) {
+            warnings.push({ code: 'MISSING_PARENT_BY_ADDRESS', message: `Capability ${id} (${x}.${y}.${z}) has no L2 parent at ${x}.${y}.0` });
+        }
+        else if (y !== 0 && z === 0 && !addressToId.has(`${x}.0.0`)) {
+            warnings.push({ code: 'MISSING_PARENT_BY_ADDRESS', message: `Capability ${id} (${x}.${y}.0) has no L1 parent at ${x}.0.0` });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/capability-map/index.d.ts

@@ -4,3 +4,12 @@ export type { CapabilityTreeNode, CapabilityTreeEdge, CapabilityTreeLevelCounts,
 export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
 export type { RenderCapabilityTreeOptions } from './render-capability-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.js';
+export type { Capability, CapabilityMap, MaturitySnapshot, MutationResult, LayoutOptions, LaidOutNode, LaidOutEdge, CapabilityMapLayout, } from './dsm-schema.js';
+export { parseAddress, formatAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken, } from './address.js';
+export { validateCapabilityMapData } from './dsm-validate.js';
+export { layoutCapabilityMap } from './dsm-layout.js';
+export { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from './dsm-mutations.js';
+export { CapabilityMapView } from './CapabilityMapView.js';
+export type { CapabilityMapViewProps, CapabilityMapChange } from './CapabilityMapView.js';
+export type { ThemeTokens } from './dsm-theme.js';
+export { DEFAULT_MATURITY_COLOURS } from './dsm-theme.js';

package/dist/capability-map/index.js

@@ -1,3 +1,9 @@
 export { validateCapabilityMap } from './validate.js';
 export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.js';
+export { parseAddress, formatAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken, } from './address.js';
+export { validateCapabilityMapData } from './dsm-validate.js';
+export { layoutCapabilityMap } from './dsm-layout.js';
+export { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from './dsm-mutations.js';
+export { CapabilityMapView } from './CapabilityMapView.js';
+export { DEFAULT_MATURITY_COLOURS } from './dsm-theme.js';

package/dist/codex/__tests__/example.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codex/__tests__/example.test.js

@@ -0,0 +1,33 @@
+// Conformance test for CODEX worked examples under
+// `tests/fixtures/notation-corpus/codex/` — pins #518 Phase C2 corpus signal.
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateCodex, folderJurisdictionFromPath } from '../validate.js';
+const corpusRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/codex');
+function codexFixturePaths() {
+    const out = [];
+    for (const zone of ['external/EU', 'internal']) {
+        const dir = path.join(corpusRoot, zone);
+        for (const f of readdirSync(dir).filter((x) => x.endsWith('.yaml'))) {
+            const rel = path.join('codex', zone, f).replace(/\\/g, '/');
+            out.push({
+                rel,
+                folderJurisdiction: folderJurisdictionFromPath(rel),
+            });
+        }
+    }
+    return out;
+}
+describe('codex worked examples (notation-corpus)', () => {
+    for (const { rel, folderJurisdiction } of codexFixturePaths()) {
+        it(`validates ${rel} without error`, () => {
+            const data = yaml.load(readFileSync(path.join(corpusRoot, rel.replace(/^codex\//, '')), 'utf-8'));
+            const v = validateCodex(data, { folderJurisdiction });
+            expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+            expect(v.errors).toHaveLength(0);
+        });
+    }
+});

package/dist/codex/__tests__/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { validateCodex, isCodexDoc, folderJurisdictionFromPath, } from '../validate.js';
+const VALID_EXTERNAL = {
+    zone: 'codex',
+    id: 'LAW-GDPR-1',
+    name: 'General Data Protection Regulation',
+    type: 'LAW',
+    jurisdiction: 'eu',
+    effective_date: '2018-05-25',
+    admitted_at: '2026-06-01',
+    admitted_by: 'legal.team',
+    gate_checks: { uniqueness: 'pass' },
+};
+const VALID_INTERNAL = {
+    zone: 'codex',
+    id: 'INTERNAL_STANDARD-coding-conventions-1',
+    name: 'Engineering Coding Conventions',
+    type: 'INTERNAL_STANDARD',
+    issuing_authority: 'VP Engineering',
+    effective_date: '2026-01-01',
+    admitted_at: '2026-05-27',
+    admitted_by: 'vp.engineering',
+    gate_checks: { source_authority: 'VP Engineering' },
+};
+describe('validateCodex', () => {
+    it('accepts a valid external artefact', () => {
+        const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'eu' });
+        expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    });
+    it('accepts a valid internal artefact', () => {
+        expect(validateCodex(VALID_INTERNAL).valid).toBe(true);
+    });
+    it('CODEX-001 rejects non-mapping input', () => {
+        expect(validateCodex(null).errors.some((e) => e.code === 'CODEX-001')).toBe(true);
+    });
+    it('CODEX-001 rejects wrong zone', () => {
+        const r = validateCodex({ ...VALID_EXTERNAL, zone: 'canon' });
+        expect(r.errors.some((e) => e.code === 'CODEX-001' && e.path === 'zone')).toBe(true);
+    });
+    it('CODEX-002 rejects type/id prefix mismatch', () => {
+        const r = validateCodex({ ...VALID_EXTERNAL, type: 'REGULATION' });
+        expect(r.errors.some((e) => e.code === 'CODEX-002')).toBe(true);
+    });
+    it('CODEX-003 requires jurisdiction on external artefacts', () => {
+        const r = validateCodex({ ...VALID_EXTERNAL, jurisdiction: '' });
+        expect(r.errors.some((e) => e.code === 'CODEX-003' && e.path === 'jurisdiction')).toBe(true);
+    });
+    it('CODEX-005 enforces folder jurisdiction match', () => {
+        const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'ge' });
+        expect(r.errors.some((e) => e.code === 'CODEX-005')).toBe(true);
+    });
+    it('CODEX-004 requires issuing_authority on internal artefacts', () => {
+        const r = validateCodex({ ...VALID_INTERNAL, issuing_authority: '' });
+        expect(r.errors.some((e) => e.code === 'CODEX-004')).toBe(true);
+    });
+});
+describe('isCodexDoc', () => {
+    it('detects zone: codex', () => {
+        expect(isCodexDoc({ zone: 'codex', id: 'LAW-1' })).toBe(true);
+        expect(isCodexDoc({ zone: 'canon' })).toBe(false);
+    });
+});
+describe('folderJurisdictionFromPath', () => {
+    it('parses codex/external/<jurisdiction>/ paths', () => {
+        expect(folderJurisdictionFromPath('codex/external/eu/LAW-GDPR-1.yaml')).toBe('eu');
+        expect(folderJurisdictionFromPath('codex/internal/POLICY-1.yaml')).toBeUndefined();
+    });
+});

package/dist/codex/index.d.ts

@@ -0,0 +1,4 @@
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export type { CodexArtefactType } from './types.js';
+export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';
+export type { CodexValidateOptions } from './validate.js';

package/dist/codex/index.js

@@ -0,0 +1,2 @@
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';

package/dist/codex/types.d.ts

@@ -0,0 +1,7 @@
+/** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
+export declare const CODEX_ARTEFACT_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
+/** External codex artefacts (codex/external/<jurisdiction>/). */
+export declare const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[];
+/** Internal codex artefacts (codex/internal/). */
+export declare const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[];

package/dist/codex/types.js

@@ -0,0 +1,8 @@
+// Codex artefact — external laws/regulations and internal policies/standards.
+// Schema: methodology notations/elements/14-codex.md §3–§4.
+/** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+/** External codex artefacts (codex/external/<jurisdiction>/). */
+export const EXTERNAL_CODEX_TYPES = ['LAW', 'REGULATION'];
+/** Internal codex artefacts (codex/internal/). */
+export const INTERNAL_CODEX_TYPES = ['POLICY', 'INTERNAL_STANDARD'];

package/dist/codex/validate.d.ts

@@ -0,0 +1,11 @@
+import type { ValidationResult } from '../validation-types.js';
+export interface CodexValidateOptions {
+    /** Lowercased jurisdiction folder segment from `codex/external/<jurisdiction>/`. */
+    folderJurisdiction?: string;
+}
+export declare function validateCodex(input: unknown, options?: CodexValidateOptions): ValidationResult;
+/** True when a parsed document is a codex-zone artefact candidate. */
+export declare function isCodexDoc(data: unknown): boolean;
+/** Infer codex folder jurisdiction from a repo-relative path such as
+ *  `codex/external/eu/LAW-GDPR-1.yaml` → `eu`. */
+export declare function folderJurisdictionFromPath(filePath: string): string | undefined;

package/dist/codex/validate.js

@@ -0,0 +1,103 @@
+// CODEX validator — methodology notations/elements/14-codex.md §4.
+//
+// CODEX-001 — shape, zone, id grammar, admission envelope.
+// CODEX-002 — `type` field matches the id TYPE prefix when present.
+// CODEX-003 — external artefact frontmatter (jurisdiction, effective_date).
+// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date).
+// CODEX-005 — jurisdiction must match the parent folder under codex/external/
+//             (when `folderJurisdiction` is supplied by the repo sweep).
+import { isCanonicalId, typeOfId } from '../typed-id.js';
+import { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, } from './types.js';
+function isCodexType(type) {
+    return type !== null && CODEX_ARTEFACT_TYPES.includes(type);
+}
+function normalizeType(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    return value.trim().toUpperCase();
+}
+export function validateCodex(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'CODEX-001', message: 'Codex artefact must be a YAML mapping.' });
+        return { valid: false, errors, warnings };
+    }
+    const c = input;
+    if (c.zone !== 'codex') {
+        errors.push({ code: 'CODEX-001', message: 'zone must be the fixed value "codex".', path: 'zone' });
+    }
+    const idType = typeOfId(c.id);
+    if (!isCanonicalId(c.id) || !isCodexType(idType)) {
+        errors.push({
+            code: 'CODEX-001',
+            message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, or INTERNAL_STANDARD).`,
+            path: 'id',
+        });
+    }
+    if (typeof c.name !== 'string' || c.name.trim() === '') {
+        errors.push({ code: 'CODEX-001', message: 'name is required.', path: 'name' });
+    }
+    for (const field of ['admitted_at', 'admitted_by']) {
+        const v = c[field];
+        if (typeof v !== 'string' || v.trim() === '') {
+            errors.push({ code: 'CODEX-001', message: `${field} is required.`, path: field });
+        }
+    }
+    if (c.gate_checks === null || typeof c.gate_checks !== 'object' || Array.isArray(c.gate_checks)) {
+        errors.push({ code: 'CODEX-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+    }
+    const declaredType = normalizeType(c.type);
+    if (declaredType !== undefined && idType && declaredType !== idType) {
+        errors.push({
+            code: 'CODEX-002',
+            message: `type "${String(c.type)}" does not match the id TYPE prefix "${idType}".`,
+            path: 'type',
+        });
+    }
+    const artefactType = (declaredType ?? idType);
+    if (artefactType && EXTERNAL_CODEX_TYPES.includes(artefactType)) {
+        const jurisdiction = typeof c.jurisdiction === 'string' ? c.jurisdiction.trim() : '';
+        if (!jurisdiction) {
+            errors.push({ code: 'CODEX-003', message: 'jurisdiction is required for external codex artefacts.', path: 'jurisdiction' });
+        }
+        else if (options.folderJurisdiction && jurisdiction.toLowerCase() !== options.folderJurisdiction.toLowerCase()) {
+            errors.push({
+                code: 'CODEX-005',
+                message: `jurisdiction "${jurisdiction}" must match the parent folder "${options.folderJurisdiction}" (CODEX-001).`,
+                path: 'jurisdiction',
+            });
+        }
+        if (typeof c.effective_date !== 'string' || c.effective_date.trim() === '') {
+            errors.push({ code: 'CODEX-003', message: 'effective_date is required for external codex artefacts.', path: 'effective_date' });
+        }
+    }
+    if (artefactType && INTERNAL_CODEX_TYPES.includes(artefactType)) {
+        if (typeof c.issuing_authority !== 'string' || c.issuing_authority.trim() === '') {
+            errors.push({
+                code: 'CODEX-004',
+                message: 'issuing_authority is required for internal codex artefacts.',
+                path: 'issuing_authority',
+            });
+        }
+        if (typeof c.effective_date !== 'string' || c.effective_date.trim() === '') {
+            errors.push({ code: 'CODEX-004', message: 'effective_date is required for internal codex artefacts.', path: 'effective_date' });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/** True when a parsed document is a codex-zone artefact candidate. */
+export function isCodexDoc(data) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data))
+        return false;
+    return data.zone === 'codex';
+}
+/** Infer codex folder jurisdiction from a repo-relative path such as
+ *  `codex/external/eu/LAW-GDPR-1.yaml` → `eu`. */
+export function folderJurisdictionFromPath(filePath) {
+    const parts = filePath.replace(/\\/g, '/').toLowerCase().split('/');
+    const extIdx = parts.indexOf('external');
+    if (extIdx < 0 || extIdx + 1 >= parts.length)
+        return undefined;
+    return parts[extIdx + 1] || undefined;
+}

package/dist/compliance/__tests__/canon-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compliance/__tests__/canon-catalog.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { admitDocumentToCatalog, buildComplianceScan, catalogFromMap, } from '../canon-catalog.js';
+describe('buildComplianceScan', () => {
+    it('admits codex, requirement, and assertion ids into the catalogue', () => {
+        const docs = [
+            {
+                path: 'codex/external/ge/LAW-PERSONAL-DATA-2017-1.yaml',
+                data: {
+                    zone: 'codex',
+                    id: 'LAW-PERSONAL-DATA-2017-1',
+                    name: 'Law',
+                    type: 'LAW',
+                },
+            },
+            {
+                path: 'canon/elements/01_motivation/requirements/REQUIREMENT-DATA-ERASURE-1.yaml',
+                data: {
+                    notation: 'requirement',
+                    id: 'REQUIREMENT-DATA-ERASURE-1',
+                    name: 'Erasure',
+                    derived_from: ['LAW-PERSONAL-DATA-2017-1'],
+                },
+            },
+            {
+                path: 'canon/elements/02_business/products/PRODUCT-MOBILE-1.yaml',
+                data: { notation: 'product', id: 'PRODUCT-MOBILE-1', name: 'Mobile' },
+            },
+            {
+                path: 'canon/assertions/ASSERTION-MOBILE-DATA-ERASURE-1.yaml',
+                data: {
+                    notation: 'assertion',
+                    id: 'ASSERTION-MOBILE-DATA-ERASURE-1',
+                    about: 'REQUIREMENT-DATA-ERASURE-1',
+                    subject: 'PRODUCT-MOBILE-1',
+                    status: 'compliant',
+                },
+            },
+        ];
+        const { catalog, complianceCanon, pathById } = buildComplianceScan(docs);
+        expect(catalog.typeOf('LAW-PERSONAL-DATA-2017-1')).toBe('LAW');
+        expect(catalog.typeOf('REQUIREMENT-DATA-ERASURE-1')).toBe('REQUIREMENT');
+        expect(catalog.typeOf('PRODUCT-MOBILE-1')).toBe('PRODUCT');
+        expect(complianceCanon.requirements).toHaveLength(1);
+        expect(complianceCanon.assertions).toHaveLength(1);
+        expect(complianceCanon.codex).toHaveLength(1);
+        expect(pathById.get('REQUIREMENT-DATA-ERASURE-1')).toContain('requirements/');
+    });
+});
+describe('admitDocumentToCatalog', () => {
+    it('uses explicit codex type when the id prefix is ambiguous', () => {
+        const map = new Map();
+        admitDocumentToCatalog(map, {
+            zone: 'codex',
+            id: 'INTERNAL_STANDARD-coding-conventions-1',
+            type: 'INTERNAL_STANDARD',
+        });
+        const catalog = catalogFromMap(map);
+        expect(catalog.typeOf('INTERNAL_STANDARD-coding-conventions-1')).toBe('INTERNAL_STANDARD');
+    });
+});

package/dist/compliance/__tests__/trace.test.d.ts

@@ -0,0 +1 @@
+export {};