@transitrix/diagrams 1.14.0 → 1.16.0

package/dist/compliance/catalogue.d.ts

@@ -0,0 +1,17 @@
+/** Relative POSIX paths keep scanning policy and content identity independent of host APIs. */
+export interface RequirementCatalogueIO {
+    read(path: string): Promise<string>;
+    list(path: string): Promise<Array<{
+        name: string;
+        kind: 'file' | 'directory' | 'symlink' | 'other';
+    }>>;
+    missing(error: unknown): boolean;
+    parse(content: string): unknown;
+    digest(content: string): string;
+    sourcePath?(path: string): string;
+}
+/** Shared disk/editor policy: one manifest boundary, all three zones, lossless failures. */
+export declare function scanRequirementCatalogue(io: RequirementCatalogueIO): Promise<{
+    canon: import("./classify.js").ComplianceCanon;
+    snapshotId: string;
+}>;

package/dist/compliance/catalogue.js

@@ -0,0 +1,68 @@
+import { emptyCanon, ingestComplianceDoc } from './classify.js';
+/** Shared disk/editor policy: one manifest boundary, all three zones, lossless failures. */
+export async function scanRequirementCatalogue(io) {
+    const canon = emptyCanon();
+    const transcript = [];
+    const manifest = await io.read('transitrix.yaml');
+    const parsed = io.parse(manifest);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('Invalid transitrix.yaml manifest: expected a mapping');
+    transcript.push(['transitrix.yaml', manifest]);
+    const fail = (path, message) => {
+        transcript.push(['failure', path, message]);
+        canon.findings.push({ id: `${path}:load`, owner: path, field: '', code: 'LOAD', message, reference: false, severity: 'error' });
+    };
+    const walk = async (dir, top = false) => {
+        let entries;
+        try {
+            entries = await io.list(dir);
+        }
+        catch (error) {
+            if (top && io.missing(error)) {
+                transcript.push(['absent-zone', dir]);
+                return;
+            }
+            fail(dir, 'Directory could not be enumerated');
+            return;
+        }
+        if (!top && entries.some(e => e.name === 'transitrix.yaml')) {
+            transcript.push(['catalogue-boundary', dir]);
+            return;
+        }
+        for (const { name, kind } of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const path = `${dir}/${name}`;
+            if (kind === 'symlink') {
+                fail(path, 'Symbolic link was not enumerated');
+                continue;
+            }
+            if (kind === 'directory') {
+                await walk(path);
+                continue;
+            }
+            if (!/\.ya?ml$/i.test(name))
+                continue;
+            if (kind !== 'file') {
+                fail(path, 'Unsupported file type');
+                continue;
+            }
+            let content;
+            try {
+                content = await io.read(path);
+            }
+            catch {
+                fail(path, 'Unreadable YAML record');
+                continue;
+            }
+            transcript.push([path, content]);
+            try {
+                ingestComplianceDoc(canon, io.parse(content), io.sourcePath?.(path) ?? path);
+            }
+            catch {
+                fail(path, 'Malformed YAML record');
+            }
+        }
+    };
+    for (const zone of ['canon', 'codex', 'field'])
+        await walk(zone, true);
+    return { canon, snapshotId: `sha256:${io.digest(JSON.stringify(transcript))}` };
+}

package/dist/compliance/index.d.ts

@@ -19,6 +19,8 @@ export { assertionToScoringElement, complianceConfidenceHeader, requirementToSco
 export { parseCoverageMetricConfig, buildCoverageMatrix, collectCoverageViewResolutionFindings, } from './coverage-metric.js';
 export type { CoverageMetricConfig, CoverageMetricRegimes, CoverageMetricRegimesFilter, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, CoverageViewFinding, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.js';
 export type { ComplianceIndex, ComplianceIndexInput, DeadlineStatus, IndexRequirement, IndexAssertion, IndexVerification, IndexNeed, IndexValidation, LawTree, LawTreeRequirement, ProductView, ProductRequirementStatus, ObjectDetailDef, ObjectDetailInput, RequirementTrace, TraceAssertionRow, TraceVerificationRow, TraceElementCatalog, TraceElementRef, TraceSourceRef, } from './types.js';
-export { buildRequirementChain, requirementReleaseCounts, selectRequirementChain, RequirementChainSnapshot, CHAIN_STAGES, chainDate } from './requirement-chain.js';
-export type { ChainInput, ChainScope, ChainSet, RequirementChainNode, RequirementChainEdge, RequirementChainProjection } from './requirement-chain.js';
+export { buildSubjectRequirementChain, buildRequirementChain, requirementReleaseCounts, selectRequirementChain, RequirementChainSnapshot, CHAIN_STAGES, chainDate } from './requirement-chain.js';
+export type { ChainSubject, ChainInput, ChainScope, ChainSet, RequirementChainNode, RequirementChainEdge, RequirementChainProjection } from './requirement-chain.js';
 export type { ChainRecord, ChainFinding } from './types.js';
+export { scanRequirementCatalogue } from './catalogue.js';
+export type { RequirementCatalogueIO } from './catalogue.js';

package/dist/compliance/index.js

@@ -11,4 +11,5 @@ export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
 export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, collectImpactViewResolutionFindings, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
 export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
 export { parseCoverageMetricConfig, buildCoverageMatrix, collectCoverageViewResolutionFindings, } from './coverage-metric.js';
-export { buildRequirementChain, requirementReleaseCounts, selectRequirementChain, RequirementChainSnapshot, CHAIN_STAGES, chainDate } from './requirement-chain.js';
+export { buildSubjectRequirementChain, buildRequirementChain, requirementReleaseCounts, selectRequirementChain, RequirementChainSnapshot, CHAIN_STAGES, chainDate } from './requirement-chain.js';
+export { scanRequirementCatalogue } from './catalogue.js';

package/dist/compliance/requirement-chain.d.ts

@@ -1,7 +1,12 @@
 import type { ChainRecord, ChainFinding, ComplianceIndex } from './types.js';
 export declare const CHAIN_STAGES: readonly ["Source document", "Driver", "Need", "Stakeholder requirement", "System requirement", "Software requirement", "Unclassified requirement", "Verification definition", "Result"];
+export interface ChainSubject {
+    type: 'PRODUCT' | 'APPLICATION';
+    id: string;
+}
 export interface ChainScope {
     catalogue: string;
+    subject?: ChainSubject;
     product?: string;
     release?: string;
     project?: string;
@@ -46,7 +51,7 @@ export interface ChainAssignment {
     relations: string[];
 }
 export interface RequirementChainProjection {
-    contract: 'requirement-chain/0.2';
+    contract: 'requirement-chain/0.2' | 'requirement-chain/0.3';
     contractRevision: string;
     asAt: string;
     snapshotId: string;
@@ -89,8 +94,14 @@ export interface RequirementChainProjection {
     executions: Record<string, string[]>;
 }
 export declare function chainDate(v: unknown): v is string;
-/** Pure, lossless release projection; no legacy coverage verdict is reinterpreted. */
+/** Explicit PRODUCT compatibility adapter for requirement-chain/0.2. */
 export declare function buildRequirementChain(input: ChainInput): RequirementChainProjection;
+/** Subject-aware 0.3 entry point; both versions use the same deterministic projection. */
+export declare function buildSubjectRequirementChain(input: ChainInput & {
+    scope: ChainScope & {
+        subject: ChainSubject;
+    };
+}): RequirementChainProjection;
 /** Both is two independent walks, never an expansion from the union frontier. */
 export declare function selectRequirementChain(p: RequirementChainProjection, focus?: string, direction?: 'upstream' | 'downstream' | 'both'): {
     nodes: RequirementChainNode[];

package/dist/compliance/requirement-chain.js

@@ -26,10 +26,28 @@ function freeze(value) {
 }
 const CODEX = ['LAW', 'REGULATION', 'STANDARD', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 const FIELD = ['INTERVIEW', 'SURVEY', 'OBSERVATION', 'DRAFT'];
-/** Pure, lossless release projection; no legacy coverage verdict is reinterpreted. */
+/** Explicit PRODUCT compatibility adapter for requirement-chain/0.2. */
 export function buildRequirementChain(input) {
+    if (input.scope.subject)
+        throw new Error('Use buildSubjectRequirementChain for explicit subjects');
+    return projectRequirementChain(input);
+}
+/** Subject-aware 0.3 entry point; both versions use the same deterministic projection. */
+export function buildSubjectRequirementChain(input) {
+    if (input.scope.product !== undefined)
+        throw new Error('Conflicting product and subject selectors');
+    if (!['PRODUCT', 'APPLICATION'].includes(input.scope.subject.type))
+        throw new Error('Unsupported subject type');
+    return projectRequirementChain(input);
+}
+/** Pure, lossless release projection; no legacy coverage verdict is reinterpreted. */
+function projectRequirementChain(input) {
     var _a;
     const { index, asAt, scope } = input;
+    const subject = scope.subject ?? { type: 'PRODUCT', id: scope.product };
+    const membershipKind = subject.type === 'APPLICATION' ? 'application_scope' : 'product_scope';
+    const pairKind = subject.type === 'APPLICATION' ? 'project_application' : 'project_product';
+    const subjectWord = scope.subject ? 'subject' : 'product';
     const findings = structuredClone(index.findings);
     const scopeFindings = [];
     const records = new Map();
@@ -39,7 +57,7 @@ export function buildRequirementChain(input) {
         if (!findings.some(f => f.id === id && f.code === code))
             findings.push({ id, owner, field, code, message, reference, severity: warning ? 'warning' : 'error' });
     };
-    for (const [id, versions] of index.recordsById) {
+    for (const [id, versions] of [...index.recordsById].sort(([a], [b]) => a.localeCompare(b))) {
         if (versions.length !== 1) {
             finding(id, 'id', 'DUPLICATE', 'Ambiguous catalogue identity');
             complete = false;
@@ -109,7 +127,7 @@ export function buildRequirementChain(input) {
             node(r, 2);
         else if (r.type === 'DRIVER')
             node(r, 1);
-        else if (['PRODUCT', 'RELEASE', 'ACTION'].includes(r.type))
+        else if (['PRODUCT', 'APPLICATION', 'RELEASE', 'ACTION'].includes(r.type))
             node(r, -1);
         else if (CODEX.includes(r.type) || FIELD.includes(r.type)) {
             node(r, 0);
@@ -165,13 +183,15 @@ export function buildRequirementChain(input) {
         const src = records.get(from), dst = records.get(to);
         const endpoints = kind === 'requirement_parent' ? is(from, 'REQUIREMENT') && is(to, 'REQUIREMENT') :
             kind === 'serves' ? is(from, 'REQUIREMENT') && is(to, 'NEED') :
-                kind === 'product_scope' ? is(from, 'REQUIREMENT') && is(to, 'PRODUCT') :
-                    kind === 'project_scope' ? is(from, 'REQUIREMENT') && isProject(to) :
-                        kind === 'project_product' ? isProject(from) && is(to, 'PRODUCT') :
-                            kind === 'required_for' ? is(from, 'REQUIREMENT') && is(to, 'RELEASE') :
-                                kind === 'source_trace' ? !!src && !!dst && envelope.get(from) === true && envelope.get(to) === true &&
-                                    (['REQUIREMENT', 'NEED'].includes(src.type) && (dst.type === 'DRIVER' || FIELD.includes(dst.type)) ||
-                                        src.type === 'DRIVER' && FIELD.includes(dst.type)) : !!src && !!dst;
+                kind === 'application_scope' ? is(from, 'REQUIREMENT') && is(to, 'APPLICATION') :
+                    kind === 'project_application' ? isProject(from) && is(to, 'APPLICATION') :
+                        kind === 'product_scope' ? is(from, 'REQUIREMENT') && is(to, 'PRODUCT') :
+                            kind === 'project_scope' ? is(from, 'REQUIREMENT') && isProject(to) :
+                                kind === 'project_product' ? isProject(from) && is(to, 'PRODUCT') :
+                                    kind === 'required_for' ? is(from, 'REQUIREMENT') && is(to, 'RELEASE') :
+                                        kind === 'source_trace' ? !!src && !!dst && envelope.get(from) === true && envelope.get(to) === true &&
+                                            (['REQUIREMENT', 'NEED'].includes(src.type) && (dst.type === 'DRIVER' || FIELD.includes(dst.type)) ||
+                                                src.type === 'DRIVER' && FIELD.includes(dst.type)) : !!src && !!dst;
         const temporal = contains(r, src) && contains(r, dst);
         if (!temporal)
             finding(r.id, 'to', 'REL-003', 'Relation window must be contained in both endpoints', true);
@@ -207,38 +227,38 @@ export function buildRequirementChain(input) {
         }
     }
     const memberships = (id, kind) => rels.filter(r => usable.has(r.id) && r.raw.type === kind && r.raw.from === id).map(r => String(r.raw.to));
-    const unresolved = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').length === 0).map(r => r.id);
-    const P = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').includes(scope.product ?? '')).map(r => r.id);
+    const unresolved = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').length === 0 && (!scope.subject || memberships(r.id, 'application_scope').length === 0)).map(r => r.id);
+    const P = requirements.filter(r => active.get(r.id) && memberships(r.id, membershipKind).includes(subject.id ?? '')).map(r => r.id);
     let productComplete = complete && unresolved.length === 0;
     if (unresolved.length)
-        scopeFindings.push('Unresolved product membership');
-    if (requirements.some(r => !envelope.get(r.id)) || rels.some(r => r.raw.type === 'product_scope' && active.get(r.id) && !usable.has(r.id)))
+        scopeFindings.push(`Unresolved ${subjectWord} membership`);
+    if (requirements.some(r => !envelope.get(r.id)) || rels.some(r => r.raw.type === membershipKind && active.get(r.id) && !usable.has(r.id)))
         productComplete = false;
     const invalidAssignments = new Set();
     for (const r of rels.filter(r => r.raw.type === 'required_for')) {
         const from = String(r.raw.from), to = records.get(String(r.raw.to));
         const historical = chainDate(r.raw.valid_to) && r.raw.valid_to < asAt;
         const future = chainDate(r.raw.valid_from) && r.raw.valid_from > asAt;
-        if (!historical && !future && (!usable.has(r.id) || !memberships(from, 'product_scope').includes(String(to?.raw.of)))) {
+        if (!historical && !future && (!usable.has(r.id) || ![...memberships(from, 'product_scope'), ...(scope.subject ? memberships(from, 'application_scope') : [])].includes(String(to?.raw.of)))) {
             invalidAssignments.add(from);
-            finding(r.id, 'to', 'ASSIGNMENT', 'Invalid, dangling or wrong-product assignment', true);
+            finding(r.id, 'to', 'ASSIGNMENT', `Invalid, dangling or wrong-${subjectWord} assignment`, true);
             if (!envelope.get(r.id))
                 productComplete = false;
         }
     }
     let selectedComplete = complete;
-    if (!is(scope.product, 'PRODUCT')) {
+    if (!is(subject.id, subject.type)) {
         productComplete = false;
         selectedComplete = false;
-        scopeFindings.push('Product unselected or unresolved');
+        scopeFindings.push(scope.subject ? 'Subject unselected or unresolved' : 'Product unselected or unresolved');
     }
-    if (!is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== scope.product) {
+    if (!is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== subject.id) {
         selectedComplete = false;
-        scopeFindings.push('Release unselected, unresolved or wrong product');
+        scopeFindings.push(`Release unselected, unresolved or wrong ${subjectWord}`);
     }
-    if (scope.project && (!isProject(scope.project) || !memberships(scope.project, 'project_product').includes(scope.product ?? ''))) {
+    if (scope.project && (!isProject(scope.project) || !memberships(scope.project, pairKind).includes(subject.id ?? ''))) {
         selectedComplete = false;
-        scopeFindings.push('Invalid or unmodelled project/product pair');
+        scopeFindings.push(`Invalid or unmodelled project/${subjectWord} pair`);
     }
     function query(release) {
         const chain = [];
@@ -246,9 +266,9 @@ export function buildRequirementChain(input) {
         let valid = true;
         while (cursor) {
             const r = records.get(cursor);
-            if (chain.includes(cursor) || !is(cursor, 'RELEASE') || r?.raw.of !== scope.product) {
+            if (chain.includes(cursor) || !is(cursor, 'RELEASE') || r?.raw.of !== subject.id) {
                 valid = false;
-                finding(chain[chain.length - 1] ?? release, 'predecessor', 'RELEASE-SCOPE', chain.includes(cursor) ? 'Release predecessor cycle' : 'Missing, invalid or cross-product predecessor');
+                finding(chain[chain.length - 1] ?? release, 'predecessor', 'RELEASE-SCOPE', chain.includes(cursor) ? 'Release predecessor cycle' : `Missing, invalid or cross-${subjectWord} predecessor`);
                 break;
             }
             chain.push(cursor);
@@ -275,16 +295,16 @@ export function buildRequirementChain(input) {
         selectedComplete = false;
         scopeFindings.push('Unresolved project membership');
     }
-    if (rels.some(r => ['product_scope', 'project_scope', 'required_for'].includes(String(r.raw.type)) && !envelope.get(r.id)))
+    if (rels.some(r => [membershipKind, 'project_scope', 'required_for'].includes(String(r.raw.type)) && !envelope.get(r.id)))
         selectedComplete = false;
-    if (scope.project && L.some(id => memberships(id, 'project_scope').some(project => !memberships(project, 'project_product').includes(scope.product ?? '')))) {
+    if (scope.project && L.some(id => memberships(id, 'project_scope').some(project => !memberships(project, pairKind).includes(subject.id ?? '')))) {
         selectedComplete = false;
-        scopeFindings.push('Inconsistent project/product membership');
+        scopeFindings.push(`Inconsistent project/${subjectWord} membership`);
     }
     const S = L.filter(id => !scope.project || memberships(id, 'project_scope').includes(scope.project));
     const elsewhere = new Set();
     for (const release of records.values())
-        if (release.type === 'RELEASE' && release.raw.of === scope.product) {
+        if (release.type === 'RELEASE' && release.raw.of === subject.id) {
             const q = query(release.id);
             productComplete && (productComplete = q.complete);
             q.ids.forEach(id => elsewhere.add(id));
@@ -352,7 +372,7 @@ export function buildRequirementChain(input) {
             if (v.raw.verifies === r.id)
                 owners.add(v.id);
         for (const rel of rels) {
-            const ownScope = ['product_scope', 'project_scope', 'required_for'].includes(String(rel.raw.type));
+            const ownScope = [membershipKind, 'project_scope', 'required_for'].includes(String(rel.raw.type));
             if (ownScope ? rel.raw.from === r.id : owners.has(String(rel.raw.from)))
                 owners.add(rel.id);
         }
@@ -379,15 +399,17 @@ export function buildRequirementChain(input) {
     const broken = S.filter(id => selectedRefs.some(f => affectedRequirements[f.id]?.includes(id)));
     for (const n of nodes)
         if (records.get(n.recordId)?.type === 'REQUIREMENT' && !S.includes(n.recordId)) {
-            n.context.push(!active.get(n.recordId) ? 'inactive' : !P.includes(n.recordId) ? 'unresolved or other product' :
+            n.context.push(!active.get(n.recordId) ? 'inactive' : !P.includes(n.recordId) ? `unresolved or other ${subjectWord}` :
                 !L.includes(n.recordId) ? 'other release or unassigned' : 'other project');
         }
+    if (scope.subject && (!is(subject.id, subject.type) || !is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== subject.id))
+        productComplete = false;
     const unassignedSet = set(unassigned, productComplete);
     const result = {
-        contract: 'requirement-chain/0.2', contractRevision: '97c9d41819011ead8fe192c266cba32707eae82f', asAt, snapshotId: input.snapshotId, sourceRevision: input.sourceRevision,
+        contract: scope.subject ? 'requirement-chain/0.3' : 'requirement-chain/0.2', contractRevision: scope.subject ? 'a131b1862d86f34be8feb729e1cc6ebc994c3891' : '97c9d41819011ead8fe192c266cba32707eae82f', asAt, snapshotId: input.snapshotId, sourceRevision: input.sourceRevision,
         scope: structuredClone(scope), completeness: productComplete && selectedComplete ? 'complete' : 'incomplete', scopeFindings: sorted(scopeFindings),
         populations: { product: set(P, productComplete), release: set(L, selectedComplete), selected: set(S, selectedComplete),
-            inactive: set(requirements.filter(r => envelope.get(r.id) && !active.get(r.id) && rels.some(rel => rel.raw.type === 'product_scope' && rel.raw.from === r.id && rel.raw.to === scope.product && envelope.get(rel.id))).map(r => r.id), complete),
+            inactive: set(requirements.filter(r => envelope.get(r.id) && !active.get(r.id) && rels.some(rel => rel.raw.type === membershipKind && rel.raw.from === r.id && rel.raw.to === subject.id && envelope.get(rel.id))).map(r => r.id), complete),
             unresolved: set(unresolved, complete) },
         assignments: { here: set(L, selectedComplete), otherReleaseOnly: set(P.filter(id => elsewhere.has(id) && !L.includes(id)), productComplete),
             unassigned: unassignedSet, invalid: set(P.filter(id => invalidAssignments.has(id)), complete), provenance: selected.provenance.sort((a, b) => a.requirement.localeCompare(b.requirement)) },
@@ -474,6 +496,9 @@ export function requirementReleaseCounts(p) {
     const contextUnits = { 0: 'source documents', 1: 'drivers', 2: 'needs', 7: 'definition parts', 8: 'result parts' };
     for (const stage of [0, 1, 2, 7, 8])
         add('context-' + stage, CHAIN_STAGES[stage], set(view.nodes.filter(n => n.stage === stage).map(n => n.id), p.populations.selected.completeness === 'complete'), contextUnits[stage]);
+    if (p.scope.subject)
+        for (const count of Object.values(counts))
+            count.label = count.label.replace(/whole product/g, 'whole subject').replace('Product requirements', 'Subject requirements');
     return freeze(counts);
 }
 /** Monotonic refresh gate shared by reports; late successes and failures cannot replace newer data. */
@@ -488,7 +513,9 @@ export class RequirementChainSnapshot {
             const input = await load();
             if (generation !== this.generation)
                 return false;
-            this.current = buildRequirementChain(input);
+            this.current = input.scope.subject
+                ? buildSubjectRequirementChain({ ...input, scope: { ...input.scope, subject: input.scope.subject } })
+                : buildRequirementChain(input);
             this.stale = false;
             return true;
         }

package/dist/products/types.d.ts

@@ -1,4 +1,4 @@
-export type ProductType = 'digital_product' | 'service' | 'platform' | 'bundle';
+export type ProductType = 'physical_product' | 'digital_product' | 'service' | 'platform' | 'bundle';
 export type ProductStatus = 'Draft' | 'Active' | 'Deprecated';
 export interface Product {
     product_id: string;

package/dist/products/validate.js

@@ -1,5 +1,5 @@
 import { schemaFinding } from '../schema-finding.js';
-const VALID_TYPES = new Set(['digital_product', 'service', 'platform', 'bundle']);
+const VALID_TYPES = new Set(['physical_product', 'digital_product', 'service', 'platform', 'bundle']);
 const VALID_STATUSES = new Set(['Draft', 'Active', 'Deprecated']);
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 export function validateProductsCatalogue(input) {

package/dist/standalone/history.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type StandaloneOptions } from './validate.js';
+export declare function validateHistory(input: unknown, options?: StandaloneOptions): ValidationResult;

package/dist/standalone/history.js

@@ -0,0 +1,67 @@
+import { mapping, isoDate } from './validate.js';
+import { validateAttributeArray } from '../versioned-attribute/validate.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+export function validateHistory(input, options = {}) {
+    const errors = [], warnings = [];
+    const fail = (field, expected, actual, code = 'SCHEMA_INVALID') => errors.push({ code, message: `history sidecar: ${field}: expected ${expected}; actual ${JSON.stringify(actual) ?? 'missing'}.`, path: field });
+    if (!mapping(input)) {
+        fail('$', 'mapping', input);
+        return { valid: false, errors, warnings };
+    }
+    const d = input;
+    if (typeof d.target !== 'string' || !d.target.trim())
+        fail('target', 'canonical target ID', d.target, 'VERSIONED-001');
+    const target = typeof d.target === 'string' ? options.documents?.get(d.target) : undefined;
+    if (options.documents && (!target || !options.catalog?.typeOf(d.target)))
+        fail('target', 'admitted primitive', d.target, 'VERSIONED-001');
+    const notation = target?.notation;
+    const attributes = { capability: ['current_maturity', 'target_maturity', 'target_date', 'owner_role'], application: ['maturity', 'vendor', 'owner_role'] };
+    const allowed = typeof notation === 'string' ? attributes[notation] : undefined;
+    if (!allowed)
+        warnings.push({ code: 'NOTATION-SKIP-001', message: 'History target schema is unavailable; attribute coverage remains unvalidated.' });
+    if (!mapping(d.attribute_versions))
+        fail('attribute_versions', 'mapping', d.attribute_versions);
+    else
+        for (const [attribute, entries] of Object.entries(d.attribute_versions)) {
+            const field = `attribute_versions.${attribute}`;
+            if (allowed && !allowed.includes(attribute))
+                fail(field, 'declared time_varying attribute', attribute);
+            if (!Array.isArray(entries)) {
+                fail(field, 'array', entries);
+                continue;
+            }
+            const checked = [];
+            for (const [i, entry] of entries.entries()) {
+                const key = `${field}[${i}]`;
+                if (!mapping(entry)) {
+                    fail(key, 'mapping', entry);
+                    continue;
+                }
+                if (!isoDate(entry.valid_from))
+                    fail(`${key}.valid_from`, 'ISO calendar date', entry.valid_from);
+                const value = entry.value;
+                const scalar = value === null || ['string', 'number', 'boolean'].includes(typeof value);
+                if (!('value' in entry) || !scalar)
+                    fail(`${key}.value`, 'scalar or null', value);
+                if (scalar && isoDate(entry.valid_from))
+                    checked.push({ valid_from: entry.valid_from, value: value });
+                if (value === null || !allowed?.includes(attribute))
+                    continue;
+                if (['current_maturity', 'target_maturity', 'maturity'].includes(attribute) && !(Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 5))
+                    fail(`${key}.value`, 'integer 1..5 or null', value);
+                if (attribute === 'target_date' && !isoDate(value))
+                    fail(`${key}.value`, 'ISO calendar date or null', value);
+                if (attribute === 'vendor' && typeof value !== 'string')
+                    fail(`${key}.value`, 'string or null', value);
+                if (attribute === 'owner_role' && (!isCanonicalIdOfType(value, 'ROLE') || (options.catalog && options.catalog.typeOf(value) !== 'ROLE')))
+                    fail(`${key}.value`, 'admitted ROLE reference or null', value);
+            }
+            for (const finding of validateAttributeArray(attribute, checked, typeof target?.valid_from === 'string' ? target.valid_from : undefined, target?.valid_to === null || typeof target?.valid_to === 'string' ? target.valid_to : undefined)) {
+                (finding.severity === 'error' ? errors : warnings).push({ code: finding.code, message: finding.message });
+            }
+        }
+    for (const key of ['notation', 'id', 'zone', 'admitted_at', 'admitted_by', 'valid_from', 'valid_to'])
+        if (key in d)
+            fail(key, 'absent on headerless history sidecar', d[key]);
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/standalone/validate.d.ts

@@ -0,0 +1,9 @@
+import { type CanonCatalog } from '../typed-id.js';
+import type { ValidationResult } from '../validation-types.js';
+export declare const mapping: (v: unknown) => v is Record<string, unknown>;
+export declare const isoDate: (v: unknown) => v is string;
+export interface StandaloneOptions {
+    catalog?: CanonCatalog;
+    documents?: ReadonlyMap<string, Record<string, unknown>>;
+}
+export declare function validateStandalone(notation: string, input: unknown, options?: StandaloneOptions): ValidationResult;