@transitrix/diagrams 1.8.21 → 1.10.0

package/src/agreement.ts

@@ -0,0 +1,71 @@
+// 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.
+
+import type { ValidationError } from './validation-types.js';
+
+export const AGREEMENT_VALUES = ['draft', 'agreed', 'disputed'] as const;
+export type AgreementValue = (typeof AGREEMENT_VALUES)[number];
+
+/** 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: unknown): boolean {
+  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: Record<string, unknown>): ValidationError[] {
+  const agreement = record.agreement;
+  if (agreement === undefined) return [];
+
+  if (typeof agreement !== 'string' || !(AGREEMENT_VALUES as readonly string[]).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/src/applications/index.ts

@@ -9,3 +9,6 @@ export type {
 } from './types.js';
 
 export { validateApplicationsCatalogue } from './validate.js';
+
+export type { ResolvedApplicationAttributes } from './resolve-maturity.js';
+export { resolveApplicationAttributes, withResolvedAttributes } from './resolve-maturity.js';

package/src/applications/resolve-maturity.ts

@@ -0,0 +1,66 @@
+// 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';
+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 function resolveApplicationAttributes(
+  rawElementDocs: unknown[],
+  atDate: string,
+): Map<string, ResolvedApplicationAttributes> {
+  const byAppId = new Map<string, ResolvedApplicationAttributes>();
+  for (const doc of rawElementDocs) {
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) continue;
+    const sidecar = parseSidecar(doc as Record<string, unknown>);
+    if (!sidecar) continue;
+    const resolved = resolveAttributes(sidecar, atDate);
+    const entry: ResolvedApplicationAttributes = {};
+    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: Application,
+  resolved: Map<string, ResolvedApplicationAttributes>,
+): Application {
+  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/src/applications/validate.ts

@@ -12,6 +12,17 @@ const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
 const IFACE_CONDITIONAL = ['protocol', 'payload_class', 'sensitivity', 'directionality'] as const;
 
+// 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'] as const;
+
 export function validateApplicationsCatalogue(input: unknown): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
@@ -114,6 +125,18 @@ export function validateApplicationsCatalogue(input: unknown): ValidationResult
       }
     }
 
+    // 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'] as unknown[];

package/src/capability-map/index.ts

@@ -7,6 +7,13 @@ export type {
 
 export { validateCapabilityMap } from './validate.js';
 
+export type { ResolvedCapabilityAttributes } from './resolve-maturity.js';
+export {
+  resolveCapabilityAttributes,
+  withResolvedAttributes,
+  withResolvedCapabilityMap,
+} from './resolve-maturity.js';
+
 export type {
   CapabilityTreeNode,
   CapabilityTreeEdge,

package/src/capability-map/resolve-maturity.ts

@@ -0,0 +1,84 @@
+// 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';
+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 function resolveCapabilityAttributes(
+  rawElementDocs: unknown[],
+  atDate: string,
+): Map<string, ResolvedCapabilityAttributes> {
+  const byId = new Map<string, ResolvedCapabilityAttributes>();
+  for (const doc of rawElementDocs) {
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) continue;
+    const sidecar = parseSidecar(doc as Record<string, unknown>);
+    if (!sidecar) continue;
+    const resolved = resolveAttributes(sidecar, atDate);
+    const entry: ResolvedCapabilityAttributes = {};
+    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: CapabilityNode,
+  resolved: Map<string, ResolvedCapabilityAttributes>,
+): CapabilityNode {
+  const r = resolved.get(node.id);
+  const merged: CapabilityNode = 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: CapabilityMapHeader,
+  resolved: Map<string, ResolvedCapabilityAttributes>,
+): CapabilityMapHeader {
+  if (resolved.size === 0) return map;
+  return { ...map, capabilities: map.capabilities.map((c) => withResolvedAttributes(c, resolved)) };
+}

package/src/capability-map/validate.ts

@@ -8,8 +8,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: unknown): ValidationResult {

package/src/codex/index.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/src/codex/types.ts

@@ -1,13 +1,21 @@
-// 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'] as const;
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'] as const;
 
 export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
 
 /** External codex artefacts (codex/external/<jurisdiction>/). */
 export const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['LAW', 'REGULATION'];
 
-/** Internal codex artefacts (codex/internal/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['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: readonly CodexArtefactType[] = ['PRINCIPLE'];

package/src/codex/validate.ts

@@ -3,9 +3,20 @@
 // 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 type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 import { isCanonicalId, typeOfId } from '../typed-id.js';
@@ -13,6 +24,7 @@ import {
   CODEX_ARTEFACT_TYPES,
   EXTERNAL_CODEX_TYPES,
   INTERNAL_CODEX_TYPES,
+  PRINCIPLE_CODEX_TYPES,
   type CodexArtefactType,
 } from './types.js';
 
@@ -48,7 +60,7 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
   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',
     });
   }
@@ -106,6 +118,22 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
     }
   }
 
+  if (artefactType && (PRINCIPLE_CODEX_TYPES as readonly string[]).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 };
 }
 

package/src/compliance/classify.ts

@@ -1,10 +1,12 @@
-// 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.
 
 import type { AssertionStatus } from '../assertion/types.js';
-import type { IndexAssertion, IndexRequirement } from './types.js';
+import type { VerificationMethod, VerificationOutcome } from '../verification/types.js';
+import type { ValidationMethod, ValidationOutcome } from '../validation/types.js';
+import type { IndexAssertion, IndexRequirement, IndexVerification, IndexNeed, IndexValidation } from './types.js';
 
 export interface ComplianceProduct {
   id: string;
@@ -22,6 +24,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`:
@@ -29,22 +33,64 @@ 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 function emptyCanon(): ComplianceCanon {
-  return { products: [], requirements: [], assertions: [], codex: [], subjects: [] };
+  return {
+    products: [],
+    requirements: [],
+    assertions: [],
+    verifications: [],
+    codex: [],
+    subjects: [],
+    needs: [],
+    validations: [],
+    duplicateIds: [],
+  };
 }
 
 const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
 const strArray = (v: unknown): string[] | undefined =>
   Array.isArray(v) ? v.filter((x): x is string => 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<T extends { id: string }>(canon: ComplianceCanon, list: T[], item: T): boolean {
+  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: ComplianceCanon, doc: unknown): string | null {
   if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return null;
@@ -53,8 +99,7 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
   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' ||
@@ -62,12 +107,11 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
     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),
@@ -79,15 +123,32 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
       element_kind: d.notation,
       description: str(d.description),
       next_review_at: str(d.next_review_at),
+      serves: str(d.serves),
+    });
+    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) as ValidationMethod | undefined;
+    const outcome = str(d.outcome) as ValidationOutcome | undefined;
+    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 id;
+    return ok ? id : null;
   }
   if (d.notation === 'assertion') {
     const about = str(d.about);
     const subject = str(d.subject);
     const status = str(d.status) as AssertionStatus | undefined;
     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),
@@ -96,11 +157,23 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
       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) as VerificationMethod | undefined;
+    const outcome = str(d.outcome) as VerificationOutcome | undefined;
+    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/src/compliance/confidence.ts

@@ -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