@transitrix/diagrams 1.8.21 → 1.10.0

package/dist/activity-card/types.js

@@ -1,7 +1,7 @@
 // Activity Card notation — single-project narrative view.
 //
 // Spec: transitrix/methodology `notations/views/18-activity-card.md` (v0.1).
-// Epic vkgeorgia/strategy#97, Studio track #134.
+// Studio track #134.
 //
 // The Activity Card is the first MULTI-DOCUMENT Studio notation. The card
 // YAML itself holds only `id`, `project` (an Activity ID), `description`,

package/dist/agreement.d.ts

@@ -0,0 +1,15 @@
+import type { ValidationError } from './validation-types.js';
+export declare const AGREEMENT_VALUES: readonly ["draft", "agreed", "disputed"];
+export type AgreementValue = (typeof AGREEMENT_VALUES)[number];
+export declare function looksLikeTool(id: unknown): boolean;
+/**
+ * AGREE-001..003 over an element's already-extracted `agreement` /
+ * `agreed_by` fields. Returns an empty list when `agreement` is absent
+ * (back-compat — absent ⇒ `agreed`, nothing to check) or when the fields
+ * are well-formed.
+ *
+ * AGREE-002 and AGREE-003 can both describe an `agreement: agreed` record
+ * with no `agreed_by` — this reports AGREE-003 only, the same choice
+ * `check-agreement.mjs` makes (CONTRACT.md §6.3.1 permits either or both).
+ */
+export declare function checkAgreement(record: Record<string, unknown>): ValidationError[];

package/dist/agreement.js

@@ -0,0 +1,61 @@
+// Agreement axis — methodology CONTRACT.md §6.3 / §6.3.1 (AGREE-001..003).
+//
+// A closed three-value axis (`draft` | `agreed` | `disputed`) carried by
+// REQUIREMENT, CONSTRAINT, and NEED — independent of admission (§6.1),
+// recording whether the accountable party has committed to the statement.
+// Absent ⇒ `agreed` (back-compat; a human-authored element that predates
+// this axis needs no change).
+//
+// Ported from methodology's reference implementation
+// (`scripts/check-agreement.mjs`'s `checkAgreement`/`looksLikeTool`) so a
+// repo carrying the field validates identically here — same closed
+// vocabulary, same tool-id heuristic, same "AGREE-003 wins over AGREE-002
+// when both would fire" precedence.
+export const AGREEMENT_VALUES = ['draft', 'agreed', 'disputed'];
+/** Same convention as `ADMIT-007`'s footgun-catcher: an npm-scoped name, or
+ *  a hyphenated `*-cli` / `*-reviewer[-…]` / `*-bot` / `*-scanner` id, reads
+ *  as a tool; anything else reads as a human handle. Not a security
+ *  boundary — catches the common mistake of a tool defaulting or
+ *  copy-pasting `agreed`. */
+const TOOL_ID_RE = /^@|-cli$|-reviewer(?:-\w+)?$|-bot$|-scanner$/i;
+export function looksLikeTool(id) {
+    return TOOL_ID_RE.test(String(id ?? ''));
+}
+/**
+ * AGREE-001..003 over an element's already-extracted `agreement` /
+ * `agreed_by` fields. Returns an empty list when `agreement` is absent
+ * (back-compat — absent ⇒ `agreed`, nothing to check) or when the fields
+ * are well-formed.
+ *
+ * AGREE-002 and AGREE-003 can both describe an `agreement: agreed` record
+ * with no `agreed_by` — this reports AGREE-003 only, the same choice
+ * `check-agreement.mjs` makes (CONTRACT.md §6.3.1 permits either or both).
+ */
+export function checkAgreement(record) {
+    const agreement = record.agreement;
+    if (agreement === undefined)
+        return [];
+    if (typeof agreement !== 'string' || !AGREEMENT_VALUES.includes(agreement)) {
+        return [{
+                code: 'AGREE-001',
+                message: `agreement "${String(agreement)}" must be one of ${AGREEMENT_VALUES.join(', ')}.`,
+                path: 'agreement',
+            }];
+    }
+    const agreedBy = record.agreed_by;
+    if (typeof agreedBy !== 'string' || agreedBy.trim() === '') {
+        return [{
+                code: 'AGREE-003',
+                message: 'agreed_by is required whenever agreement is present.',
+                path: 'agreed_by',
+            }];
+    }
+    if (agreement === 'agreed' && looksLikeTool(agreedBy)) {
+        return [{
+                code: 'AGREE-002',
+                message: `agreement: agreed but agreed_by "${agreedBy}" identifies a tool — a tool must never write "agreed".`,
+                path: 'agreed_by',
+            }];
+    }
+    return [];
+}

package/dist/applications/index.d.ts

@@ -1,2 +1,4 @@
 export type { ApplicationType, ApplicationStatus, IntegrationDirection, ApplicationIntegration, Application, ApplicationsCatalogueHeader, ApplicationsCatalogueFile, } from './types.js';
 export { validateApplicationsCatalogue } from './validate.js';
+export type { ResolvedApplicationAttributes } from './resolve-maturity.js';
+export { resolveApplicationAttributes, withResolvedAttributes } from './resolve-maturity.js';

package/dist/applications/index.js

@@ -1 +1,2 @@
 export { validateApplicationsCatalogue } from './validate.js';
+export { resolveApplicationAttributes, withResolvedAttributes } from './resolve-maturity.js';

package/dist/applications/resolve-maturity.d.ts

@@ -0,0 +1,16 @@
+import type { Application } from './types.js';
+export interface ResolvedApplicationAttributes {
+    owner_role?: string;
+    vendor?: string;
+    maturity?: number;
+}
+/** Pick every sidecar out of a raw canon/elements/** doc pool and resolve
+ *  owner_role/vendor/maturity at `atDate`, keyed by the sidecar's target id
+ *  (== an application's `app_id`, per the notation's element-file pairing). */
+export declare function resolveApplicationAttributes(rawElementDocs: unknown[], atDate: string): Map<string, ResolvedApplicationAttributes>;
+/** Merge resolved sidecar values into a rendering copy of an application row.
+ *  An inline value would win if present, but VERSIONED-004 already forbids
+ *  that on an admitted document — this is a display fallback, not a
+ *  migration tool. The returned object is a plain copy; nothing here writes
+ *  it anywhere. */
+export declare function withResolvedAttributes(app: Application, resolved: Map<string, ResolvedApplicationAttributes>): Application;

package/dist/applications/resolve-maturity.js

@@ -0,0 +1,57 @@
+// Render-time resolution of the applications-catalogue's sidecar-bound
+// time_varying fields (owner_role, vendor, maturity — notations/views/
+// 10-applications.md §5a, CONTRACT.md §9.4). VERSIONED-004 rejects these
+// inline on an admitted catalogue entry, so a compliant document never
+// carries them — a renderer that only reads the document straight shows
+// blank cells for every field the maturity decision moved out.
+//
+// Pure: no I/O, no repo walk. The host (VS Code extension, IntelliJ/JCEF,
+// CLI) already owns loading canon/elements/** (canon-loader.ts's shared FS
+// layer) — this module only knows how to pick sidecars out of that pool and
+// resolve them at a date.
+//
+// Per the 2026-08-05 hub decision (proposal #1022): this is a read model,
+// never storage. Callers render an augmented, ephemeral copy of the
+// application row and must never serialise it back — the sidecar stays the
+// only place these fields are written.
+import { parseSidecar, resolveAttributes } from '../versioned-attribute/index.js';
+/** Pick every sidecar out of a raw canon/elements/** doc pool and resolve
+ *  owner_role/vendor/maturity at `atDate`, keyed by the sidecar's target id
+ *  (== an application's `app_id`, per the notation's element-file pairing). */
+export function resolveApplicationAttributes(rawElementDocs, atDate) {
+    const byAppId = new Map();
+    for (const doc of rawElementDocs) {
+        if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+            continue;
+        const sidecar = parseSidecar(doc);
+        if (!sidecar)
+            continue;
+        const resolved = resolveAttributes(sidecar, atDate);
+        const entry = {};
+        if (typeof resolved['owner_role'] === 'string')
+            entry.owner_role = resolved['owner_role'];
+        if (typeof resolved['vendor'] === 'string')
+            entry.vendor = resolved['vendor'];
+        if (typeof resolved['maturity'] === 'number')
+            entry.maturity = resolved['maturity'];
+        if (Object.keys(entry).length > 0)
+            byAppId.set(sidecar.target, entry);
+    }
+    return byAppId;
+}
+/** Merge resolved sidecar values into a rendering copy of an application row.
+ *  An inline value would win if present, but VERSIONED-004 already forbids
+ *  that on an admitted document — this is a display fallback, not a
+ *  migration tool. The returned object is a plain copy; nothing here writes
+ *  it anywhere. */
+export function withResolvedAttributes(app, resolved) {
+    const r = resolved.get(app.app_id);
+    if (!r)
+        return app;
+    return {
+        ...app,
+        owner_role: app.owner_role ?? r.owner_role,
+        vendor: app.vendor ?? r.vendor,
+        maturity: app.maturity ?? r.maturity,
+    };
+}

package/dist/applications/validate.js

@@ -5,6 +5,16 @@ const VALID_SENSITIVITY = new Set(['public', 'internal', 'confidential', 'restri
 const VALID_DIRECTIONALITY = new Set(['producer', 'consumer', 'request_reply', 'bidirectional_stream']);
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const IFACE_CONDITIONAL = ['protocol', 'payload_class', 'sensitivity', 'directionality'];
+// VERSIONED-004 (CONTRACT.md §9.3) — `owner_role`, `vendor`, `maturity` are
+// declared `time_varying` by notations/views/10-applications.md §5/§5a and
+// belong in the sidecar `<app_id>.history.yaml`, not inline on the catalogue
+// entry. Unlike capability's VERSIONED-004 (packages/diagrams/src/
+// repo-validate/check-versioned-attributes.ts), which walks standalone
+// element files under canon/elements/**, an applications-catalogue entry has
+// no file of its own to check inline-vs-sidecar on — the entry lives in this
+// view document — so the check runs here, at the per-file notation
+// validator, rather than in the repo-scope element sweep.
+const TIME_VARYING_FIELDS = ['owner_role', 'vendor', 'maturity'];
 export function validateApplicationsCatalogue(input) {
     const errors = [];
     const warnings = [];
@@ -92,6 +102,16 @@ export function validateApplicationsCatalogue(input) {
                 errors.push({ code: 'APP-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
             }
         }
+        // VERSIONED-004: time_varying fields must live in the sidecar, not inline.
+        for (const field of TIME_VARYING_FIELDS) {
+            if (a[field] !== undefined) {
+                errors.push({
+                    code: 'VERSIONED-004',
+                    message: `${idx}: '${field}' is time_varying (CONTRACT.md §9) and belongs in the sidecar ` +
+                        `'${typeof a['app_id'] === 'string' ? a['app_id'] : idx}.history.yaml', not inline on the catalogue entry.`,
+                });
+            }
+        }
         // APP-009: integrations[].direction enum
         if (Array.isArray(a['integrations'])) {
             const integrations = a['integrations'];

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

@@ -15,5 +15,5 @@ export interface CapabilityCardNodeData {
 }
 declare const CapabilityCardNode: React.MemoExoticComponent<({ data }: {
     data: CapabilityCardNodeData;
-}) => import("react/jsx-runtime").JSX.Element>;
+}) => React.JSX.Element>;
 export default CapabilityCardNode;

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

@@ -8,5 +8,5 @@ export interface CapabilityRootNodeData {
  *  add/delete/collapse affordances (it isn't a mutable Capability). */
 declare const CapabilityRootNode: React.MemoExoticComponent<({ data }: {
     data: CapabilityRootNodeData;
-}) => import("react/jsx-runtime").JSX.Element>;
+}) => React.JSX.Element>;
 export default CapabilityRootNode;

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

@@ -1,5 +1,7 @@
 export type { CapabilityType, CapabilityNode, CapabilityMapHeader, CapabilityMapFile, } from './types.js';
 export { validateCapabilityMap } from './validate.js';
+export type { ResolvedCapabilityAttributes } from './resolve-maturity.js';
+export { resolveCapabilityAttributes, withResolvedAttributes, withResolvedCapabilityMap, } from './resolve-maturity.js';
 export type { CapabilityTreeNode, CapabilityTreeEdge, CapabilityTreeLevelCounts, CapabilityTreeLayout, } from './layout-tree.js';
 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';

package/dist/capability-map/index.js

@@ -1,4 +1,5 @@
 export { validateCapabilityMap } from './validate.js';
+export { resolveCapabilityAttributes, withResolvedAttributes, withResolvedCapabilityMap, } from './resolve-maturity.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';

package/dist/capability-map/resolve-maturity.d.ts

@@ -0,0 +1,20 @@
+import type { CapabilityMapHeader, CapabilityNode } from './types.js';
+export interface ResolvedCapabilityAttributes {
+    current_maturity?: number;
+    target_maturity?: number;
+    owner_role?: string;
+    target_date?: string;
+}
+/** Pick every sidecar out of a raw canon/elements/** doc pool and resolve
+ *  current_maturity/target_maturity/owner_role/target_date at `atDate`,
+ *  keyed by the sidecar's target id (== a capability entry's `id`, per the
+ *  CAPABILITY-* primitive that entry references). */
+export declare function resolveCapabilityAttributes(rawElementDocs: unknown[], atDate: string): Map<string, ResolvedCapabilityAttributes>;
+/** Merge resolved sidecar values into a rendering copy of a capability node
+ *  and its descendants. An inline value always wins if present — this is a
+ *  display fallback for fields the document doesn't carry inline, not a
+ *  migration tool. Returns a new node tree; nothing here writes it
+ *  anywhere. */
+export declare function withResolvedAttributes(node: CapabilityNode, resolved: Map<string, ResolvedCapabilityAttributes>): CapabilityNode;
+/** Same merge, applied across a capability map's whole top-level tree. */
+export declare function withResolvedCapabilityMap(map: CapabilityMapHeader, resolved: Map<string, ResolvedCapabilityAttributes>): CapabilityMapHeader;

package/dist/capability-map/resolve-maturity.js

@@ -0,0 +1,72 @@
+// Render-time resolution of a nested capability-map entry's sidecar-bound
+// time_varying fields (current_maturity, target_maturity, owner_role,
+// target_date — 05-capability-map.md §13/§14, CONTRACT.md §9.4).
+// check-versioned-attributes.ts's VERSIONED-004 already rejects these inline
+// on the standalone CAPABILITY-*.yaml primitive; a nested capability-map
+// entry references that same primitive by id (the 2026-08-05 packages
+// decision — no separate per-nested-entry sidecar convention), so this
+// resolves the same way applications/resolve-maturity.ts does for the
+// applications catalogue.
+//
+// Pure: no I/O, no repo walk. The host (VS Code extension, IntelliJ/JCEF,
+// CLI) already owns loading canon/elements/** — this module only knows how
+// to pick sidecars out of that pool and resolve them at a date.
+//
+// Per the 2026-08-05 packages decision: this is a read model, never
+// storage. Callers render an augmented, ephemeral copy of the capability
+// tree and must never serialise it back — the sidecar stays the only place
+// these fields are written.
+import { parseSidecar, resolveAttributes } from '../versioned-attribute/index.js';
+/** Pick every sidecar out of a raw canon/elements/** doc pool and resolve
+ *  current_maturity/target_maturity/owner_role/target_date at `atDate`,
+ *  keyed by the sidecar's target id (== a capability entry's `id`, per the
+ *  CAPABILITY-* primitive that entry references). */
+export function resolveCapabilityAttributes(rawElementDocs, atDate) {
+    const byId = new Map();
+    for (const doc of rawElementDocs) {
+        if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+            continue;
+        const sidecar = parseSidecar(doc);
+        if (!sidecar)
+            continue;
+        const resolved = resolveAttributes(sidecar, atDate);
+        const entry = {};
+        if (typeof resolved['current_maturity'] === 'number')
+            entry.current_maturity = resolved['current_maturity'];
+        if (typeof resolved['target_maturity'] === 'number')
+            entry.target_maturity = resolved['target_maturity'];
+        if (typeof resolved['owner_role'] === 'string')
+            entry.owner_role = resolved['owner_role'];
+        if (typeof resolved['target_date'] === 'string')
+            entry.target_date = resolved['target_date'];
+        if (Object.keys(entry).length > 0)
+            byId.set(sidecar.target, entry);
+    }
+    return byId;
+}
+/** Merge resolved sidecar values into a rendering copy of a capability node
+ *  and its descendants. An inline value always wins if present — this is a
+ *  display fallback for fields the document doesn't carry inline, not a
+ *  migration tool. Returns a new node tree; nothing here writes it
+ *  anywhere. */
+export function withResolvedAttributes(node, resolved) {
+    const r = resolved.get(node.id);
+    const merged = r
+        ? {
+            ...node,
+            current_maturity: node.current_maturity ?? r.current_maturity,
+            target_maturity: node.target_maturity ?? r.target_maturity,
+            owner_role: node.owner_role ?? r.owner_role,
+            target_date: node.target_date ?? r.target_date,
+        }
+        : node;
+    if (!node.children || node.children.length === 0)
+        return merged;
+    return { ...merged, children: node.children.map((c) => withResolvedAttributes(c, resolved)) };
+}
+/** Same merge, applied across a capability map's whole top-level tree. */
+export function withResolvedCapabilityMap(map, resolved) {
+    if (resolved.size === 0)
+        return map;
+    return { ...map, capabilities: map.capabilities.map((c) => withResolvedAttributes(c, resolved)) };
+}

package/dist/capability-map/validate.js

@@ -3,8 +3,7 @@ const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 // Canonical form per `IDS_AND_REFERENCES.md` §2: `CAPABILITY-V…` /
 // `CAPABILITY-H…` with the dotted address (`V1`, `V1.2.1`, `H1`). The bare
 // legacy form (`V1`, `H1`) is still accepted so existing maps without the
-// canonical prefix do not break — migration is tracked under
-// vkgeorgia/strategy#36.
+// canonical prefix do not break; migration is tracked separately.
 const CAP_ID_RE = /^(CAPABILITY-)?(V|H)\d+(\.\d+)*$/;
 export function validateCapabilityMap(input) {
     const errors = [];

package/dist/codex/index.d.ts

@@ -1,4 +1,4 @@
-export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_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

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

package/dist/codex/types.d.ts

@@ -1,7 +1,14 @@
 /** 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 declare const CODEX_ARTEFACT_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD", "PRINCIPLE"];
 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/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export declare const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[];
+/**
+ * Internal codex artefacts (codex/internal/) with the `PRINCIPLE` shape (§4.1) —
+ * `statement` + `rationale` required, `issuing_authority`/`effective_date`/`established_by`
+ * optional. Kept distinct from {@link INTERNAL_CODEX_TYPES} because the required-field set
+ * differs; both share the same file location.
+ */
+export declare const PRINCIPLE_CODEX_TYPES: readonly CodexArtefactType[];

package/dist/codex/types.js

@@ -1,8 +1,15 @@
-// Codex artefact — external laws/regulations and internal policies/standards.
+// Codex artefact — external laws/regulations and internal policies/standards/principles.
 // 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'];
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 /** External codex artefacts (codex/external/<jurisdiction>/). */
 export const EXTERNAL_CODEX_TYPES = ['LAW', 'REGULATION'];
-/** Internal codex artefacts (codex/internal/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export const INTERNAL_CODEX_TYPES = ['POLICY', 'INTERNAL_STANDARD'];
+/**
+ * Internal codex artefacts (codex/internal/) with the `PRINCIPLE` shape (§4.1) —
+ * `statement` + `rationale` required, `issuing_authority`/`effective_date`/`established_by`
+ * optional. Kept distinct from {@link INTERNAL_CODEX_TYPES} because the required-field set
+ * differs; both share the same file location.
+ */
+export const PRINCIPLE_CODEX_TYPES = ['PRINCIPLE'];

package/dist/codex/validate.js

@@ -3,11 +3,22 @@
 // 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-004 — internal artefact frontmatter (issuing_authority, effective_date for
+//             POLICY/INTERNAL_STANDARD; statement, rationale for PRINCIPLE — §4.1).
 // CODEX-005 — jurisdiction must match the parent folder under codex/external/
 //             (when `folderJurisdiction` is supplied by the repo sweep).
+// CODEX-006 — a PRINCIPLE artefact does not declare `established_by` (§4.1). The spec
+//             marks this "info" severity; this module has no info tier, so it is
+//             surfaced as a warning — the nearest existing severity that does not fail
+//             `valid`.
+//
+// Note: this file's CODEX-00x numbering predates the spec's own v0.2 renumbering
+// (14-codex.md §6, §8.2) and does not track it code-for-code — e.g. the spec's current
+// CODEX-001 is a folder/jurisdiction check this file assigns to CODEX-005. Realigning the
+// full scheme is out of scope here; this change only adds the purely-additive PRINCIPLE
+// TYPE (§4.1) under the existing local numbering.
 import { isCanonicalId, typeOfId } from '../typed-id.js';
-import { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, } from './types.js';
+import { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_CODEX_TYPES, } from './types.js';
 function isCodexType(type) {
     return type !== null && CODEX_ARTEFACT_TYPES.includes(type);
 }
@@ -31,7 +42,7 @@ export function validateCodex(input, options = {}) {
     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).`,
+            message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, INTERNAL_STANDARD, or PRINCIPLE).`,
             path: 'id',
         });
     }
@@ -84,6 +95,21 @@ export function validateCodex(input, options = {}) {
             errors.push({ code: 'CODEX-004', message: 'effective_date is required for internal codex artefacts.', path: 'effective_date' });
         }
     }
+    if (artefactType && PRINCIPLE_CODEX_TYPES.includes(artefactType)) {
+        if (typeof c.statement !== 'string' || c.statement.trim() === '') {
+            errors.push({ code: 'CODEX-004', message: 'statement is required for a PRINCIPLE artefact.', path: 'statement' });
+        }
+        if (typeof c.rationale !== 'string' || c.rationale.trim() === '') {
+            errors.push({ code: 'CODEX-004', message: 'rationale is required for a PRINCIPLE artefact.', path: 'rationale' });
+        }
+        if (typeof c.established_by !== 'string' || c.established_by.trim() === '') {
+            warnings.push({
+                code: 'CODEX-006',
+                message: 'established_by is not declared on this PRINCIPLE artefact — admissible, but a review finding for whoever admits it.',
+                path: 'established_by',
+            });
+        }
+    }
     return { valid: errors.length === 0, errors, warnings };
 }
 /** True when a parsed document is a codex-zone artefact candidate. */

package/dist/compliance/classify.d.ts

@@ -1,4 +1,4 @@
-import type { IndexAssertion, IndexRequirement } from './types.js';
+import type { IndexAssertion, IndexRequirement, IndexVerification, IndexNeed, IndexValidation } from './types.js';
 export interface ComplianceProduct {
     id: string;
     name: string;
@@ -14,6 +14,8 @@ export interface ComplianceCanon {
     products: ComplianceProduct[];
     requirements: IndexRequirement[];
     assertions: IndexAssertion[];
+    /** VERIFICATION artefacts (27-verification.md) — the engineering V&V peer of `assertions`. */
+    verifications: IndexVerification[];
     codex: ComplianceCodexDoc[];
     /**
      * Named elements that can serve as assertion subjects beyond `products`:
@@ -21,6 +23,21 @@ export interface ComplianceCanon {
      * `ingestComplianceDoc` for the corresponding notation values.
      */
     subjects: ComplianceProduct[];
+    /** NEED elements (ELEMENT_PRIMITIVES.md §7.28) — upstream of `requirements`.
+     *  Ingested so NEED-COVERAGE-001 / NEED-VALIDATION-COVERAGE-001..002 can
+     *  compute coverage over the full needs catalogue. */
+    needs: IndexNeed[];
+    /** VALIDATION artefacts (28-validation.md) — the validation-domain peer of
+     *  `verifications`, anchored on NEED instead of REQUIREMENT. */
+    validations: IndexValidation[];
+    /**
+     * Ids rejected by `ingestComplianceDoc` because that id was already present
+     * in the same bucket (two documents claiming one id — transitrix-hq#218).
+     * The second and any later document is dropped rather than silently
+     * duplicating a matrix column; callers that scan a filesystem can surface
+     * this list as a diagnostic.
+     */
+    duplicateIds: string[];
 }
 export declare function emptyCanon(): ComplianceCanon;
 /**
@@ -28,6 +45,8 @@ export declare function emptyCanon(): ComplianceCanon;
  * pushes its projection into `canon`. Products / requirements / assertions are
  * identified by their `notation` tag; codex source documents by `zone: codex`.
  * Returns the artefact id when ingested (so the caller can record its path), or
- * null when the document is not a (well-formed) compliance artefact.
+ * null when the document is not a (well-formed) compliance artefact, or when
+ * its id duplicates one already ingested into the same bucket (see
+ * `canon.duplicateIds`).
  */
 export declare function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): string | null;

package/dist/compliance/classify.js

@@ -1,18 +1,44 @@
-// Canon-artefact classification (vkgeorgia/strategy#84). The single authority
+// Canon-artefact classification. The single authority
 // for "what is a compliance artefact" — used by both the Studio extension scan
 // (webview previews) and the CLI scan (`export-compliance`), so the recognition
 // rules live once. Pure: takes a parsed YAML document, no IO.
 export function emptyCanon() {
-    return { products: [], requirements: [], assertions: [], codex: [], subjects: [] };
+    return {
+        products: [],
+        requirements: [],
+        assertions: [],
+        verifications: [],
+        codex: [],
+        subjects: [],
+        needs: [],
+        validations: [],
+        duplicateIds: [],
+    };
 }
 const str = (v) => (typeof v === 'string' ? v : undefined);
 const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+/**
+ * Pushes `item` onto `list` unless `list` already holds an entry with the same
+ * id, in which case the id is recorded in `canon.duplicateIds` and the item is
+ * dropped — two documents claiming one id is a defect (transitrix-hq#218), not
+ * a second matrix column.
+ */
+function pushUnique(canon, list, item) {
+    if (list.some(existing => existing.id === item.id)) {
+        canon.duplicateIds.push(item.id);
+        return false;
+    }
+    list.push(item);
+    return true;
+}
 /**
  * Classifies one parsed YAML document and, if it is a compliance artefact,
  * pushes its projection into `canon`. Products / requirements / assertions are
  * identified by their `notation` tag; codex source documents by `zone: codex`.
  * Returns the artefact id when ingested (so the caller can record its path), or
- * null when the document is not a (well-formed) compliance artefact.
+ * null when the document is not a (well-formed) compliance artefact, or when
+ * its id duplicates one already ingested into the same bucket (see
+ * `canon.duplicateIds`).
  */
 export function ingestComplianceDoc(canon, doc) {
     if (doc === null || typeof doc !== 'object' || Array.isArray(doc))
@@ -22,19 +48,17 @@ export function ingestComplianceDoc(canon, doc) {
     if (!id)
         return null;
     if (d.notation === 'product') {
-        canon.products.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.products, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'capability' ||
         d.notation === 'process' ||
         d.notation === 'application' ||
         d.notation === 'system') {
-        canon.subjects.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.subjects, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'requirement' || d.notation === 'constraint') {
         const origin = str(d.origin);
-        canon.requirements.push({
+        const ok = pushUnique(canon, canon.requirements, {
             id,
             name: str(d.name) ?? id,
             severity: str(d.severity),
@@ -46,8 +70,26 @@ export function ingestComplianceDoc(canon, doc) {
             element_kind: d.notation,
             description: str(d.description),
             next_review_at: str(d.next_review_at),
+            serves: str(d.serves),
         });
-        return id;
+        return ok ? id : null;
+    }
+    if (d.notation === 'need') {
+        return pushUnique(canon, canon.needs, { id, name: str(d.name) ?? id }) ? id : null;
+    }
+    if (d.notation === 'validation') {
+        const validates = str(d.validates);
+        const method = str(d.method);
+        const outcome = str(d.outcome);
+        if (!validates || !method || !outcome)
+            return null;
+        const ok = pushUnique(canon, canon.validations, {
+            id, validates, method, outcome,
+            performed_at: str(d.performed_at),
+            evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
+            admitted_at: str(d.admitted_at),
+        });
+        return ok ? id : null;
     }
     if (d.notation === 'assertion') {
         const about = str(d.about);
@@ -55,7 +97,7 @@ export function ingestComplianceDoc(canon, doc) {
         const status = str(d.status);
         if (!about || !subject || !status)
             return null;
-        canon.assertions.push({
+        const ok = pushUnique(canon, canon.assertions, {
             id, about, subject, status,
             assessed_at: str(d.assessed_at),
             next_review_at: str(d.next_review_at),
@@ -64,11 +106,24 @@ export function ingestComplianceDoc(canon, doc) {
             realised_via: strArray(d.realised_via),
             owner_to_confirm: str(d.owner_to_confirm),
         });
-        return id;
+        return ok ? id : null;
+    }
+    if (d.notation === 'verification') {
+        const verifies = str(d.verifies);
+        const method = str(d.method);
+        const outcome = str(d.outcome);
+        if (!verifies || !method || !outcome)
+            return null;
+        const ok = pushUnique(canon, canon.verifications, {
+            id, verifies, method, outcome,
+            performed_at: str(d.performed_at),
+            evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
+            admitted_at: str(d.admitted_at),
+        });
+        return ok ? id : null;
     }
     if (d.zone === 'codex') {
-        canon.codex.push({ id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) });
-        return id;
+        return pushUnique(canon, canon.codex, { id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) }) ? id : null;
     }
     return null;
 }

package/dist/compliance/confidence.js

@@ -1,4 +1,4 @@
-// Confidence bridge for the compliance views (vkgeorgia/strategy#162 — DQ-2).
+// Confidence bridge for the compliance views (DQ-2).
 // Maps the compliance index projections (IndexRequirement / IndexAssertion) onto
 // the DQ-1 ScoringElement shape, scores the view, and renders the §11.6 header
 // line. Lives in @transitrix/diagrams so Studio and DSM share one bridge and