@transitrix/diagrams 1.9.18 → 1.10.0

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

@@ -30,6 +30,14 @@ export interface ComplianceCanon {
     /** 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;
 /**
@@ -37,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

@@ -12,16 +12,33 @@ export function emptyCanon() {
         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))
@@ -31,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),
@@ -57,11 +72,10 @@ export function ingestComplianceDoc(canon, doc) {
             next_review_at: str(d.next_review_at),
             serves: str(d.serves),
         });
-        return id;
+        return ok ? id : null;
     }
     if (d.notation === 'need') {
-        canon.needs.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.needs, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'validation') {
         const validates = str(d.validates);
@@ -69,13 +83,13 @@ export function ingestComplianceDoc(canon, doc) {
         const outcome = str(d.outcome);
         if (!validates || !method || !outcome)
             return null;
-        canon.validations.push({
+        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);
@@ -83,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),
@@ -92,7 +106,7 @@ 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);
@@ -100,17 +114,16 @@ export function ingestComplianceDoc(canon, doc) {
         const outcome = str(d.outcome);
         if (!verifies || !method || !outcome)
             return null;
-        canon.verifications.push({
+        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 id;
+        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/repo-validate/check-candidate-fields.d.ts

@@ -0,0 +1,6 @@
+import type { RepoFinding, RepoModelInput } from './types.js';
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export declare function checkCandidateFields(input: RepoModelInput, findings: RepoFinding[]): void;

package/dist/repo-validate/check-candidate-fields.js

@@ -0,0 +1,87 @@
+// Candidate-only fields on admitted canon — `ADMIT-009`.
+//
+// `ELEMENT_PRIMITIVES.md` §7.29 (methodology v3.6.0) states it normatively for
+// `RELEASE` and then generalises it to every TYPE:
+//
+//   > `RELEASE` has no `extraction_confidence` field — and neither does any
+//   > other canon element, of any TYPE. `extraction_confidence` is a review
+//   > flag on an ingest candidate (`candidate.extraction_confidence`,
+//   > vocabulary.yaml); it is surfaced in the review queue, drives
+//   > reviewer-authority routing (CONTRACT.md §6.2), and is never persisted
+//   > into canon. An admitted element carrying it is a defect in whatever
+//   > wrote it, not a precedent to follow.
+//
+// Nothing enforced that mechanically. The ingest pipeline that produces the
+// field lives in `methodology`'s `packages/ingest-cli` and only ever writes
+// *candidates*; admission into `canon/elements/**` happens in an adopter's own
+// tooling, which is `@transitrix/cli validate`'s side of the fence — so this is
+// where the rule has to bite.
+//
+// **Why the check keys on `zone`, not on the folder.** `extraction_confidence`
+// is legitimate on a candidate and meaningless — but not a defect — elsewhere;
+// only the *admitted* form is wrong. `zone: canon` is the admission marker
+// every standalone element carries (`ELEMENT_PRIMITIVES.md` §3, required
+// envelope field, `ELEM-001`), and it is the discriminator against the two
+// zones that may legitimately carry harvest metadata: `zone: field`, whose
+// provenance contract owns `source_quality` (CONTRACT.md §5/§11.2), and
+// `zone: codex`. Sidecars (`*.history.yaml`, `*.runstate.yaml`) carry no
+// `zone` and no `id`, so they fall out for free — the same "no id -> not an
+// element" split `docId` already makes for every sibling check in this folder.
+//
+// **Rule code.** Studio-authored as `ELEM-CANDIDATE-FIELD-001` (in the shape
+// methodology already uses for a named element-envelope rule outside the
+// numbered run — `ELEM-ALIAS-001`, `ELEM-FORMER-ID-001` — deliberately not
+// `ELEM-006`, since the numbered `ELEM-*` run is methodology's to extend and
+// squatting the next free number would collide with whatever it registers
+// there next). Renamed to `ADMIT-009` (transitrix/methodology#505, merged
+// 2026-08-19) now that methodology has registered a code of its own for
+// §7.29 — no functional change, this is that alias.
+import { docId } from './validate-repo.js';
+const PScope = 'repo';
+/**
+ * Fields that belong to an ingest candidate and are never persisted into
+ * canon. Each entry names the field and the provenance pattern that replaces
+ * it, so the finding points at the correct shape rather than only failing
+ * closed. One entry today; the list is the extension point if methodology
+ * closes another candidate-side field out of canon the same way.
+ */
+const CANDIDATE_ONLY_FIELDS = [
+    {
+        field: 'extraction_confidence',
+        instead: "cite the evidence through 'derived_from' (ELEMENT_PRIMITIVES.md §3) — " +
+            'an OBSERVATION or another Field/Codex artefact; the review flag stays on the ' +
+            'ingest candidate and is not carried across admission',
+    },
+];
+/** True when the doc is an admitted canon element — `zone: canon` per
+ *  `ELEMENT_PRIMITIVES.md` §3. Deliberately narrow: a doc with no `zone`
+ *  (a sidecar) or a non-canon zone (`field`, `codex`) is not admitted canon
+ *  and this rule says nothing about it. */
+function isAdmittedCanonElement(doc) {
+    return doc.data?.['zone'] === 'canon';
+}
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export function checkCandidateFields(input, findings) {
+    for (const doc of input.elements) {
+        if (!doc.data)
+            continue;
+        if (!isAdmittedCanonElement(doc))
+            continue;
+        const id = docId(doc) ?? '';
+        for (const { field, instead } of CANDIDATE_ONLY_FIELDS) {
+            if (doc.data[field] === undefined)
+                continue;
+            findings.push({
+                scope: PScope,
+                id,
+                ruleId: 'ADMIT-009',
+                message: `ADMIT-009: admitted element '${id || doc.path}' carries '${field}', ` +
+                    `which is an ingest-candidate review flag and is never persisted into canon ` +
+                    `(ELEMENT_PRIMITIVES.md §7.29). Remove it and ${instead}.`,
+            });
+        }
+    }
+}

package/dist/repo-validate/validate-repo.js

@@ -29,6 +29,7 @@
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
 import { checkVersionedAttributes } from './check-versioned-attributes.js';
+import { checkCandidateFields } from './check-candidate-fields.js';
 const PScope = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
@@ -415,5 +416,8 @@ export function validateRepoModel(input) {
     checkElementHygiene(input, findings);
     // Phase 9 — versioned-attribute sidecar rules (CONTRACT.md §9, VERSIONED-001..005).
     checkVersionedAttributes(input, findings);
+    // Phase 10 — candidate-only fields on admitted canon (ELEMENT_PRIMITIVES.md
+    // §7.29, ADMIT-009).
+    checkCandidateFields(input, findings);
     return findings;
 }

package/dist/requirement/types.d.ts

@@ -7,7 +7,7 @@ export interface GateChecks {
     completeness?: string;
 }
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD", "PRINCIPLE"];
 /** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
 export type RequirementLevel = 'stakeholder' | 'system' | 'software';
 export declare const REQUIREMENT_LEVELS: readonly RequirementLevel[];

package/dist/requirement/types.js

@@ -1,6 +1,6 @@
 // REQUIREMENT — motivation-layer positive obligation.
 // Schema: methodology notations/elements/15-requirement.md §2.
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 export const REQUIREMENT_LEVELS = ['stakeholder', 'system', 'software'];
 export const REQUIREMENT_KINDS = ['functional', 'quality'];

package/dist/webview/entry.js

@@ -28,7 +28,7 @@ import yaml from 'js-yaml';
 import { validateActivities } from '../activities/index.js';
 import { validateActivityCard } from '../activity-card/index.js';
 import { validateApplicationsCatalogue } from '../applications/index.js';
-import { validateNestedBlocks } from '../blocks/index.js';
+import { validateBlocks } from '../blocks/index.js';
 import { validateCapabilityMap } from '../capability-map/validate.js';
 import { parseCanonicalFGCA, parseCanonicalFGA } from '../fgca/parse-canonical.js';
 import { parseCanonicalGoals } from '../goals/parse-canonical.js';
@@ -40,7 +40,7 @@ import { coerceDatesToIsoStrings } from '../yaml-normalize.js';
 import { renderActivitiesSvg } from './render-activities.js';
 import { renderActivityCardSvg } from './render-activity-card.js';
 import { renderApplicationsHtml } from './render-applications.js';
-import { renderBlocksSvg } from './render-blocks.js';
+import { renderBlocksSvg, renderGridSvg } from './render-blocks.js';
 import { renderCapabilityMapHtml } from './render-capability-map.js';
 import { renderFgcaSvg } from './render-fgca.js';
 import { renderGoalsSvg } from './render-goals.js';
@@ -138,8 +138,15 @@ function dispatchValidate(kind, doc) {
             return renderFromValidation('action-card', validateActivityCard(doc), () => renderActivityCardSvg(doc));
         case 'process-blueprint':
             return renderFromValidation('process-blueprint', validateProcessBlueprint(doc), () => renderProcessBlueprintSvg(doc));
-        case 'blocks':
-            return renderFromValidation('blocks', validateNestedBlocks(doc), () => renderBlocksSvg(doc));
+        case 'blocks': {
+            // Two alternative root forms (08-blocks.md §4): a `nested_blocks:`
+            // containment tree, or a `grid:` matrix subset (§4a). `validateBlocks`
+            // is the shared root-form dispatcher (BL-020 on both/neither present);
+            // mirrors the VS Code path's `hasGrid` branch in `blocks-preview.ts`.
+            const raw = (doc && typeof doc === 'object' ? doc : {});
+            const hasGrid = raw['grid'] !== undefined && raw['grid'] !== null;
+            return renderFromValidation('blocks', validateBlocks(doc), () => hasGrid ? renderGridSvg(doc) : renderBlocksSvg(doc));
+        }
         // Catalogue notations render an HTML fragment from the header nested under
         // their top-level wrapper key (`<thing>_catalogue` / `scenario` / …).
         case 'applications':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.9.18",
+  "version": "1.10.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

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

@@ -40,6 +40,14 @@ export interface ComplianceCanon {
   /** 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 {
@@ -52,6 +60,7 @@ export function emptyCanon(): ComplianceCanon {
     subjects: [],
     needs: [],
     validations: [],
+    duplicateIds: [],
   };
 }
 
@@ -59,12 +68,29 @@ const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : und
 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;
@@ -73,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' ||
@@ -82,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),
@@ -101,31 +125,30 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
       next_review_at: str(d.next_review_at),
       serves: str(d.serves),
     });
-    return id;
+    return ok ? id : null;
   }
   if (d.notation === 'need') {
-    canon.needs.push({ id, name: str(d.name) ?? id });
-    return id;
+    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;
-    canon.validations.push({
+    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),
@@ -134,24 +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;
-    canon.verifications.push({
+    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 id;
+    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/repo-validate/check-candidate-fields.ts

@@ -0,0 +1,93 @@
+// Candidate-only fields on admitted canon — `ADMIT-009`.
+//
+// `ELEMENT_PRIMITIVES.md` §7.29 (methodology v3.6.0) states it normatively for
+// `RELEASE` and then generalises it to every TYPE:
+//
+//   > `RELEASE` has no `extraction_confidence` field — and neither does any
+//   > other canon element, of any TYPE. `extraction_confidence` is a review
+//   > flag on an ingest candidate (`candidate.extraction_confidence`,
+//   > vocabulary.yaml); it is surfaced in the review queue, drives
+//   > reviewer-authority routing (CONTRACT.md §6.2), and is never persisted
+//   > into canon. An admitted element carrying it is a defect in whatever
+//   > wrote it, not a precedent to follow.
+//
+// Nothing enforced that mechanically. The ingest pipeline that produces the
+// field lives in `methodology`'s `packages/ingest-cli` and only ever writes
+// *candidates*; admission into `canon/elements/**` happens in an adopter's own
+// tooling, which is `@transitrix/cli validate`'s side of the fence — so this is
+// where the rule has to bite.
+//
+// **Why the check keys on `zone`, not on the folder.** `extraction_confidence`
+// is legitimate on a candidate and meaningless — but not a defect — elsewhere;
+// only the *admitted* form is wrong. `zone: canon` is the admission marker
+// every standalone element carries (`ELEMENT_PRIMITIVES.md` §3, required
+// envelope field, `ELEM-001`), and it is the discriminator against the two
+// zones that may legitimately carry harvest metadata: `zone: field`, whose
+// provenance contract owns `source_quality` (CONTRACT.md §5/§11.2), and
+// `zone: codex`. Sidecars (`*.history.yaml`, `*.runstate.yaml`) carry no
+// `zone` and no `id`, so they fall out for free — the same "no id -> not an
+// element" split `docId` already makes for every sibling check in this folder.
+//
+// **Rule code.** Studio-authored as `ELEM-CANDIDATE-FIELD-001` (in the shape
+// methodology already uses for a named element-envelope rule outside the
+// numbered run — `ELEM-ALIAS-001`, `ELEM-FORMER-ID-001` — deliberately not
+// `ELEM-006`, since the numbered `ELEM-*` run is methodology's to extend and
+// squatting the next free number would collide with whatever it registers
+// there next). Renamed to `ADMIT-009` (transitrix/methodology#505, merged
+// 2026-08-19) now that methodology has registered a code of its own for
+// §7.29 — no functional change, this is that alias.
+
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+/**
+ * Fields that belong to an ingest candidate and are never persisted into
+ * canon. Each entry names the field and the provenance pattern that replaces
+ * it, so the finding points at the correct shape rather than only failing
+ * closed. One entry today; the list is the extension point if methodology
+ * closes another candidate-side field out of canon the same way.
+ */
+const CANDIDATE_ONLY_FIELDS: readonly { field: string; instead: string }[] = [
+  {
+    field: 'extraction_confidence',
+    instead:
+      "cite the evidence through 'derived_from' (ELEMENT_PRIMITIVES.md §3) — " +
+      'an OBSERVATION or another Field/Codex artefact; the review flag stays on the ' +
+      'ingest candidate and is not carried across admission',
+  },
+];
+
+/** True when the doc is an admitted canon element — `zone: canon` per
+ *  `ELEMENT_PRIMITIVES.md` §3. Deliberately narrow: a doc with no `zone`
+ *  (a sidecar) or a non-canon zone (`field`, `codex`) is not admitted canon
+ *  and this rule says nothing about it. */
+function isAdmittedCanonElement(doc: RepoDoc): boolean {
+  return doc.data?.['zone'] === 'canon';
+}
+
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export function checkCandidateFields(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    if (!doc.data) continue;
+    if (!isAdmittedCanonElement(doc)) continue;
+
+    const id = docId(doc) ?? '';
+    for (const { field, instead } of CANDIDATE_ONLY_FIELDS) {
+      if (doc.data[field] === undefined) continue;
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'ADMIT-009',
+        message:
+          `ADMIT-009: admitted element '${id || doc.path}' carries '${field}', ` +
+          `which is an ingest-candidate review flag and is never persisted into canon ` +
+          `(ELEMENT_PRIMITIVES.md §7.29). Remove it and ${instead}.`,
+      });
+    }
+  }
+}

package/src/repo-validate/validate-repo.ts

@@ -30,6 +30,7 @@
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
 import { checkVersionedAttributes } from './check-versioned-attributes.js';
+import { checkCandidateFields } from './check-candidate-fields.js';
 import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
 
 const PScope: RepoFinding['scope'] = 'repo';
@@ -431,5 +432,8 @@ export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
   checkElementHygiene(input, findings);
   // Phase 9 — versioned-attribute sidecar rules (CONTRACT.md §9, VERSIONED-001..005).
   checkVersionedAttributes(input, findings);
+  // Phase 10 — candidate-only fields on admitted canon (ELEMENT_PRIMITIVES.md
+  // §7.29, ADMIT-009).
+  checkCandidateFields(input, findings);
   return findings;
 }

package/src/requirement/types.ts

@@ -13,7 +13,7 @@ export interface GateChecks {
 }
 
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'] as const;
 
 /** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
 export type RequirementLevel = 'stakeholder' | 'system' | 'software';

package/src/webview/entry.ts

@@ -32,8 +32,8 @@ import { validateActivityCard } from '../activity-card/index.js';
 import type { ActivityCardDoc } from '../activity-card/index.js';
 import { validateApplicationsCatalogue } from '../applications/index.js';
 import type { ApplicationsCatalogueFile } from '../applications/index.js';
-import { validateNestedBlocks } from '../blocks/index.js';
-import type { BlocksFile } from '../blocks/index.js';
+import { validateBlocks } from '../blocks/index.js';
+import type { BlocksFile, GridFile } from '../blocks/index.js';
 import { validateCapabilityMap } from '../capability-map/validate.js';
 import type { CapabilityMapFile } from '../capability-map/types.js';
 import { parseCanonicalFGCA, parseCanonicalFGA } from '../fgca/parse-canonical.js';
@@ -51,7 +51,7 @@ import { coerceDatesToIsoStrings } from '../yaml-normalize.js';
 import { renderActivitiesSvg } from './render-activities.js';
 import { renderActivityCardSvg } from './render-activity-card.js';
 import { renderApplicationsHtml } from './render-applications.js';
-import { renderBlocksSvg } from './render-blocks.js';
+import { renderBlocksSvg, renderGridSvg } from './render-blocks.js';
 import { renderCapabilityMapHtml } from './render-capability-map.js';
 import { renderFgcaSvg } from './render-fgca.js';
 import { renderGoalsSvg } from './render-goals.js';
@@ -218,10 +218,17 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       return renderFromValidation('process-blueprint', validateProcessBlueprint(doc), () =>
         renderProcessBlueprintSvg(doc as ProcessBlueprintFile),
       );
-    case 'blocks':
-      return renderFromValidation('blocks', validateNestedBlocks(doc), () =>
-        renderBlocksSvg(doc as BlocksFile),
+    case 'blocks': {
+      // Two alternative root forms (08-blocks.md §4): a `nested_blocks:`
+      // containment tree, or a `grid:` matrix subset (§4a). `validateBlocks`
+      // is the shared root-form dispatcher (BL-020 on both/neither present);
+      // mirrors the VS Code path's `hasGrid` branch in `blocks-preview.ts`.
+      const raw = (doc && typeof doc === 'object' ? doc : {}) as Record<string, unknown>;
+      const hasGrid = raw['grid'] !== undefined && raw['grid'] !== null;
+      return renderFromValidation('blocks', validateBlocks(doc), () =>
+        hasGrid ? renderGridSvg(doc as GridFile) : renderBlocksSvg(doc as BlocksFile),
       );
+    }
     // Catalogue notations render an HTML fragment from the header nested under
     // their top-level wrapper key (`<thing>_catalogue` / `scenario` / …).
     case 'applications':