@tiinex/core 0.1.1

package/src/transitions/transition.validate.js

@@ -0,0 +1,129 @@
+import { parseArtifactMarkdown } from '../artifacts/artifact.parse.js';
+import { rootValidate } from '../schemas/tiinex.root.v1.validate.js';
+
+export const TRANSITION_VALIDATION_SCHEMA_ID = 'tiinex.transition.validation.v1';
+
+export function validateTransitionDraft(draft = {}, parentRecord = {}) {
+  const parsed = parseArtifactMarkdown(draft.markdown || '');
+  const findings = [];
+  for (const finding of rootValidate(parsed)) {
+    findings.push(normalizeFinding(finding));
+  }
+
+  const parent = parsed.envelope?.parent || {};
+  const current = parsed.envelope?.current || {};
+  const expectedTrace = parentRecord?.id ? `record:${parentRecord.id}` : '';
+  const expectedCurrentSchema = String(draft.kind || draft.targetSchemaId || '').trim();
+  const parentBoundary = String(parent.boundary || draft.transition?.parentBoundary || '').trim();
+  const parentOrigin = String(parent.origin || '').trim();
+
+  if (expectedTrace && parent.trace !== expectedTrace) {
+    findings.push(error('transition.parent.trace.mismatch', `Draft parent Trace must preserve ${expectedTrace}.`));
+  }
+  if (!parent.trace) findings.push(error('transition.parent.trace.required', 'Transition draft must include Parent Trace.'));
+  if (!parentBoundary) findings.push(error('transition.parent.boundary.required', 'Transition draft must include Parent Boundary.'));
+  if (parentRecord?.path && !parentOrigin) findings.push(warning('transition.parent.origin.missing', 'Parent path exists but draft Origin is missing; recovery will be degraded.'));
+  if (parentRecord?.path && parentOrigin && !originMatchesPath(parentOrigin, parentRecord.path)) {
+    findings.push(warning('transition.parent.origin.unexpected', 'Draft Origin does not end with the parent canonical path.'));
+  }
+
+  if (expectedCurrentSchema && current.schema?.id !== expectedCurrentSchema) {
+    findings.push(error('transition.current.schema.mismatch', `Draft Current Schema must be ${expectedCurrentSchema}.`));
+  }
+  if (draft.status !== 'local') findings.push(error('transition.result.status.not-local', 'Transition result must stay browser-local until explicit publication/export.'));
+  if (!String(draft.sourceMode || '').startsWith('local')) findings.push(error('transition.result.sourceMode.not-local', 'Transition result sourceMode must remain local-transition/local-reference.'));
+  if (draft.source?.adapterId === 'github') findings.push(error('transition.result.github.provenance.inferred', 'Transition draft must not inherit GitHub source provenance.'));
+
+  const parentBoundaryExpectation = expectedParentBoundary(parentRecord);
+  if (parentBoundaryExpectation === 'local' && impliesGithubProvenance(parentBoundary)) {
+    findings.push(error('transition.parent.boundary.local-github-leak', 'Local parent boundary must not imply GitHub provenance.'));
+  }
+  if (parentBoundaryExpectation === 'local' && !/no github provenance inferred/i.test(parentBoundary)) {
+    findings.push(warning('transition.parent.boundary.local-weak', 'Local parent boundary should explicitly say no GitHub provenance is inferred.'));
+  }
+  if (parentBoundaryExpectation === 'github' && !/source-backed github material/i.test(parentBoundary)) {
+    findings.push(warning('transition.parent.boundary.github-weak', 'GitHub parent boundary should preserve that the parent was source-backed GitHub material.'));
+  }
+
+  if (!parsed.hasIntegrity) findings.push(error('transition.integrity.required', 'Transition draft must include draft integrity footer.'));
+  if (!draft.transition?.contract) findings.push(error('transition.contract.missing', 'Transition result must declare the transition contract.'));
+  if (!draft.transition?.type) findings.push(error('transition.type.missing', 'Transition result must declare transition type.'));
+
+  return {
+    schema: TRANSITION_VALIDATION_SCHEMA_ID,
+    ok: !findings.some((finding) => finding.severity === 'error'),
+    status: findings.some((finding) => finding.severity === 'error') ? 'invalid' : findings.some((finding) => finding.severity === 'warning') ? 'degraded' : 'valid',
+    counts: countFindings(findings),
+    findings,
+    parsed: {
+      envelopeSchemaId: parsed.envelope?.envelopeSchema?.id || '',
+      parentSchemaId: parent.schema?.id || '',
+      parentTrace: parent.trace || '',
+      parentOrigin,
+      parentBoundary,
+      currentSchemaId: current.schema?.id || '',
+      currentCreatedAt: current.createdAt || '',
+      hasIntegrity: Boolean(parsed.hasIntegrity)
+    }
+  };
+}
+
+function expectedParentBoundary(record = {}) {
+  const source = record.source || {};
+  if (source.adapterId === 'github' || source.kind === 'github-source-backed' || source.sourceKind === 'github.repo') return 'github';
+  if (source.adapterId === 'local' || source.kind === 'local-session' || String(record.sourceMode || '').startsWith('local')) return 'local';
+  return 'explicit';
+}
+
+function impliesGithubProvenance(boundary = '') {
+  const text = String(boundary || '').toLowerCase();
+  if (!text.includes('github')) return false;
+  if (/no\s+github\s+provenance\s+inferred/.test(text)) return false;
+  return /source-backed\s+github|github\s+material|github\s+provenance/.test(text);
+}
+
+function originMatchesPath(origin = '', path = '') {
+  const cleanPath = normalizePath(path);
+  const cleanOrigin = normalizePath(origin);
+  return Boolean(cleanPath && (cleanOrigin === cleanPath || cleanOrigin.endsWith(`/${cleanPath}`)));
+}
+
+function normalizePath(value = '') {
+  try {
+    const url = new URL(String(value || ''));
+    const host = url.hostname.toLowerCase();
+    if (host === 'raw.githubusercontent.com') {
+      const parts = url.pathname.split('/').filter(Boolean);
+      return parts.length >= 4 ? parts.slice(3).join('/') : parts.join('/');
+    }
+    const parts = url.pathname.split('/').filter(Boolean);
+    const blob = parts.indexOf('blob');
+    if (host.endsWith('github.com') && blob >= 0 && parts.length > blob + 2) return parts.slice(blob + 2).join('/');
+    return url.pathname.replace(/^\/+/, '');
+  } catch (error) {
+    return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/');
+  }
+}
+
+function normalizeFinding(finding = {}) {
+  return {
+    severity: finding.severity || 'info',
+    code: finding.code || 'transition.root.finding',
+    message: finding.message || 'Root validation finding.',
+    source: finding.source || 'tiinex.transition.validation.v1'
+  };
+}
+
+function countFindings(findings = []) {
+  const counts = { error: 0, warning: 0, info: 0, preserve: 0, total: 0 };
+  for (const finding of findings) {
+    const severity = finding?.severity || 'info';
+    if (counts[severity] == null) counts[severity] = 0;
+    counts[severity] += 1;
+    counts.total += 1;
+  }
+  return counts;
+}
+
+function error(code, message) { return { severity: 'error', code, message, source: TRANSITION_VALIDATION_SCHEMA_ID }; }
+function warning(code, message) { return { severity: 'warning', code, message, source: TRANSITION_VALIDATION_SCHEMA_ID }; }

package/src/validation/findings.js

@@ -0,0 +1,76 @@
+import { resolveSchemaModule } from '../schemas/resolver.js';
+
+export const FINDING_ENVELOPE_SCHEMA_ID = 'tiinex.validation.finding.v1';
+
+export function normalizeFinding(finding = {}, options = {}) {
+  const code = String(finding.code || options.code || 'validation.finding').trim();
+  const source = String(finding.source || options.source || sourceFromCode(code)).trim();
+  const registryEntry = resolveFindingDefinition(code, { source, schemaId: options.schemaId });
+  const severity = String(finding.severity || registryEntry?.severity || options.severity || 'info').trim();
+  const messageKey = String(finding.messageKey || registryEntry?.messageKey || code).trim();
+  const fixability = finding.fixability || registryEntry?.fixability || (registryEntry?.safeFix === true ? 'safe' : registryEntry?.safeFix === false ? 'none' : 'unknown');
+  return Object.freeze({
+    schema: FINDING_ENVELOPE_SCHEMA_ID,
+    severity,
+    code,
+    messageKey,
+    message: String(finding.message || registryEntry?.fallbackMessage || fallbackMessageFor(code)).trim(),
+    source,
+    fixability,
+    params: Object.freeze(Object.assign({}, registryEntry?.params || {}, finding.params || options.params || {})),
+    evidencePath: finding.evidencePath || finding.path || '',
+    qualification: finding.qualification || options.qualification || ''
+  });
+}
+
+export function normalizeFindings(findings = [], options = {}) {
+  const list = Array.isArray(findings) ? findings : Array.isArray(findings?.findings) ? findings.findings : [];
+  return list.map((finding) => normalizeFinding(finding, options));
+}
+
+export function resolveFindingDefinition(code = '', options = {}) {
+  const source = String(options.source || sourceFromCode(code) || '').trim();
+  const candidates = [];
+  if (options.schemaId) candidates.push(options.schemaId);
+  if (source && source.startsWith('tiinex.')) candidates.push(source);
+  const codePrefix = schemaIdFromFindingCode(code);
+  if (codePrefix) candidates.push(codePrefix);
+  for (const schemaId of [...new Set(candidates.filter(Boolean))]) {
+    const resolution = resolveSchemaModule({ schemaId });
+    const findings = resolution.module?.findings;
+    const exact = findDefinition(findings, code);
+    if (exact) return exact;
+  }
+  const root = resolveSchemaModule({ schemaId: 'tiinex.root.v1' }).module?.findings;
+  return findDefinition(root, code) || null;
+}
+
+function findDefinition(findings = {}, code = '') {
+  if (!findings) return null;
+  if (findings.codes && findings.codes[code]) return findings.codes[code];
+  if (findings[code]) return findings[code];
+  return null;
+}
+
+function schemaIdFromFindingCode(code = '') {
+  const text = String(code || '');
+  const parts = text.split('.');
+  if (parts[0] === 'tiinex' && parts.length >= 4) return parts.slice(0, 4).join('.');
+  return '';
+}
+
+function sourceFromCode(code = '') {
+  const text = String(code || '');
+  if (text.startsWith('root.')) return 'tiinex.root.v1';
+  if (text.startsWith('topic.')) return 'tiinex.topic.v1';
+  if (text.startsWith('evidence.')) return 'tiinex.evidence.v1';
+  if (text.startsWith('preservation.')) return 'tiinex.preservation.v1';
+  if (text.startsWith('workspace.')) return 'tiinex.workspace.v1';
+  if (text.startsWith('integrity.')) return 'tiinex.integrity.validation.v1';
+  if (text.startsWith('audit.')) return 'tiinex.audit.v1';
+  return 'tiinex.validation.v1';
+}
+
+function fallbackMessageFor(code = '') {
+  return code ? `Validation finding: ${code}` : 'Validation finding.';
+}

package/src/validation/validateArtifact.js

@@ -0,0 +1,216 @@
+import { parseArtifactMarkdown } from '../artifacts/artifact.parse.js';
+import { normalizeArtifact } from '../artifacts/artifact.normalize.js';
+import { resolveSchemaModule } from '../schemas/resolver.js';
+import { rootValidate, rootFallbackFinding } from '../schemas/tiinex.root.v1.validate.js';
+import { validateIntegrity } from '../integrity/integrity.validate.js';
+import { validatePortableContractInstance } from '../tooling/portable/schema/contract.validate.js';
+import { qualifySchemaReferenceValue, schemaReferenceAuthorityFromBinding } from '../schemas/schema.reference.js';
+import { normalizeFindings, normalizeFinding } from './findings.js';
+
+export const ARTIFACT_VALIDATION_PIPELINE_ID = 'tiinex.artifact.validation.pipeline.v1';
+
+export function validateArtifact(input = {}, options = {}) {
+  const markdown = String(input.markdown || input.record?.markdown || input.parsed?.markdown || '');
+  const parsed = input.parsed || parseArtifactMarkdown(markdown);
+  const schemaId = parsed?.envelope?.current?.schema?.id || input.schemaId || input.record?.schemaId || input.record?.currentSchemaId || '';
+  const resolution = input.resolution || resolveSchemaModule({ schemaId, checksum: input.checksum });
+  const rootFindings = normalizeFindings(rootValidate(parsed), { schemaId: 'tiinex.root.v1', qualification: 'readability-root-diagnostic' });
+  const schemaValidationAuthority = input.schemaValidationAuthority || null;
+  const machineContract = runMachineContractValidation({ markdown: markdown || parsed?.markdown || '', schemaId, resolution, validationContractOverride: input.validationContractOverride || null, schemaValidationAuthority });
+  const contractFindings = normalizeFindings(machineContract.findings, { schemaId: machineContract.schemaId || schemaId, qualification: 'machine-contract' });
+  const schemaReferenceFindings = normalizeFindings(validateDeclaredSchemaReferences(parsed, input.schemaReferenceAuthorities || null), { qualification: 'schema-reference' });
+  const integrityFindings = normalizeFindings(validateIntegrity(parsed, options.integrity), { schemaId: 'tiinex.root.v1', qualification: 'integrity' });
+  const schemaAuthorityFindings = normalizeFindings(schemaValidationAuthorityFindings(schemaValidationAuthority, schemaId), { schemaId, qualification: 'schema-validation-authority' });
+  const childValidation = runExactSchemaValidator({ parsed, schemaId, resolution, schemaValidationAuthority });
+  const childFindings = childValidation.findings;
+  const fallbackFindings = fallbackFindingsFor({ schemaId, resolution, childFindings, childValidatorRan: childValidation.ran, machineContract });
+  const findings = [...rootFindings, ...contractFindings, ...schemaReferenceFindings, ...integrityFindings, ...schemaAuthorityFindings, ...childFindings, ...fallbackFindings];
+  const validation = validationTruthFor({ parsed, schemaId, resolution, childFindings, childValidatorRan: childValidation.ran, machineContract, findings });
+  return Object.freeze({
+    schema: ARTIFACT_VALIDATION_PIPELINE_ID,
+    parsed,
+    schemaId,
+    resolution,
+    artifact: normalizeArtifact(parsed, resolution, findings),
+    findings: Object.freeze(findings),
+    contractValidation: machineContract,
+    schemaValidationAuthority,
+    validation
+  });
+}
+
+function validateDeclaredSchemaReferences(parsed = {}, contextualAuthorities = null) {
+  const references = [
+    { role: 'Envelope Schema', value: parsed?.envelope?.envelopeSchema?.raw || '', schemaId: parsed?.envelope?.envelopeSchema?.id || '' },
+    { role: 'Current Schema', value: parsed?.envelope?.current?.schema?.raw || '', schemaId: parsed?.envelope?.current?.schema?.id || '' }
+  ];
+  const parent = parsed?.envelope?.parent || {};
+  if (parent?.schema?.id || parent?.schema?.raw) references.push({ role: 'Parent Schema', value: parent?.schema?.raw || '', schemaId: parent?.schema?.id || '' });
+  const findings = [];
+  for (const reference of references) {
+    if (!reference.schemaId || !reference.value) continue;
+    const resolved = resolveSchemaModule({ schemaId: reference.schemaId });
+    if (resolved?.fallbackUsed || !resolved?.module) {
+      findings.push({ severity: 'warning', code: 'schema.reference.authority.unavailable', message: `${reference.role} authority is unavailable for ${reference.schemaId}; the declared reference is preserved without target substitution.`, source: 'tiinex.schema.reference.validation.v1', params: { field: reference.role } });
+      continue;
+    }
+    const sourceQualification = typeof resolved.module.schemaSource?.qualify === 'function' ? resolved.module.schemaSource.qualify() : null;
+    const registeredAuthority = schemaReferenceAuthorityFromBinding(reference.schemaId, resolved.module.binding || {}, sourceQualification?.authority || null, sourceQualification);
+    const contextualAuthority = contextualSchemaReferenceAuthority(contextualAuthorities, reference.role, reference.schemaId);
+    const authority = contextualAuthority || registeredAuthority;
+    const qualification = qualifySchemaReferenceValue(reference.value, authority);
+    if (qualification.state === 'qualified') continue;
+    if (qualification.schemaIdState !== 'qualified') {
+      findings.push({ severity: 'error', code: 'schema.reference.identity-contradiction', message: `${reference.role}: Declared schema identifier contradicts current semantic schema identity authority. ${qualification.findings.join(' ')}`, source: 'tiinex.schema.reference.validation.v1', params: { field: reference.role } });
+      continue;
+    }
+    if (qualification.observed?.form === 'markdown-link' && qualification.targetState === 'unqualified') {
+      findings.push({ severity: 'info', code: 'schema.reference.locator.unresolved', message: `${reference.role}: Declared schema representation locator is preserved but is not resolved by current exact material authority. Locator resolution is separate from semantic schema identity.`, source: 'tiinex.schema.reference.validation.v1' });
+      continue;
+    }
+    findings.push({ severity: 'error', code: 'schema.reference.unqualified', message: `${reference.role}: ${qualification.findings.join(' ')}`, source: 'tiinex.schema.reference.validation.v1', params: { field: reference.role } });
+  }
+  return findings;
+}
+
+
+function contextualSchemaReferenceAuthority(value = null, role = '', schemaId = '') {
+  if (!value || typeof value !== 'object') return null;
+  const key = role === 'Envelope Schema' ? 'envelope' : role === 'Current Schema' ? 'current' : role === 'Parent Schema' ? 'parent' : '';
+  const raw = (key && value[key]) || (Array.isArray(value) ? value.find((entry) => String(entry?.role || '') === role || String(entry?.schemaId || '') === schemaId) : null);
+  if (!raw || typeof raw !== 'object') return null;
+  const id = String(raw.schemaId || schemaId || '').trim();
+  if (!id || id !== schemaId) return null;
+  const exactTargets = [...new Set([...(Array.isArray(raw.exactTargets) ? raw.exactTargets : []), raw.preferredTarget || raw.target || ''].map((item) => String(item || '')).filter(Boolean))];
+  if (String(raw.resolutionState || raw.state || '') !== 'qualified') return null;
+  return Object.freeze({ ...raw, schemaId: id, exactTargets: Object.freeze(exactTargets), preferredTarget: String(raw.preferredTarget || raw.target || exactTargets[0] || '') });
+}
+
+
+function schemaValidationAuthorityFindings(authority = null, schemaId = '') {
+  if (!authority || authority.state === 'qualified') return [];
+  const detail = [...(authority.findings || [])].map((item) => String(item || '').trim()).filter(Boolean);
+  const suffix = detail.length ? ` ${detail.slice(0, 3).join(' ')}` : '';
+  return [{
+    severity: 'warning',
+    code: 'audit.schema-authority.unqualified',
+    message: `Exact schema validation is withheld for ${schemaId || authority.schemaId || 'the declared Current Schema'} because its version-bearing authority or compiled inheritance lineage is not qualified.${suffix}`,
+    source: 'tiinex.audit.v1',
+    state: 'unresolved',
+    params: { field: 'Current Schema' },
+    authorityState: String(authority.state || 'unavailable'),
+    authorityReason: String(authority.reason || '')
+  }];
+}
+
+function runMachineContractValidation({ markdown = '', schemaId = '', resolution = {}, validationContractOverride = null, schemaValidationAuthority = null } = {}) {
+  if (schemaValidationAuthority && schemaValidationAuthority.state !== 'qualified') return Object.freeze({ available: false, state: 'unavailable', schemaId, lineage: Object.freeze([]), result: null, findings: Object.freeze([]), reason: 'schema-authority-unqualified' });
+  if (resolution?.fallbackUsed) return Object.freeze({ available: false, state: 'unavailable', schemaId, lineage: Object.freeze([]), result: null, findings: Object.freeze([]), reason: 'fallback-resolution-has-no-target-contract-authority' });
+  const qualification = typeof resolution?.module?.schemaSource?.qualify === 'function' ? resolution.module.schemaSource.qualify() : null;
+  const compiledContract = validationContractOverride || (qualification?.state === 'qualified' ? qualification?.compiledContract?.validationContract || null : null);
+  if (!compiledContract || compiledContract?.lineageQualification?.state !== 'valid') {
+    return Object.freeze({
+      available: false,
+      state: 'unavailable',
+      schemaId,
+      lineage: Object.freeze([]),
+      result: null,
+      findings: Object.freeze([]),
+      reason: qualification?.state === 'qualified' ? 'compiled-validation-contract-unavailable' : 'schema-source-unqualified'
+    });
+  }
+  try {
+    const result = validatePortableContractInstance({ markdown, compiledContract });
+    return Object.freeze({
+      available: true,
+      state: String(result.status || 'unresolved'),
+      schemaId: String(compiledContract.schemaId || schemaId),
+      lineage: Object.freeze([...(compiledContract.lineage || [])]),
+      result,
+      findings: Object.freeze([...(result.findings || [])]),
+      conditionalRequirements: Object.freeze([...(compiledContract?.validation?.conditionalRequirements || [])]),
+      reason: ''
+    });
+  } catch (error) {
+    return Object.freeze({
+      available: true,
+      state: 'unresolved',
+      schemaId: String(compiledContract.schemaId || schemaId),
+      lineage: Object.freeze([...(compiledContract.lineage || [])]),
+      result: null,
+      findings: Object.freeze([{ severity: 'warning', code: 'audit.machine-contract.validation.failed', message: String(error?.message || error || 'Compiled contract validation failed.'), source: 'tiinex.audit.v1' }]),
+      reason: 'compiled-validation-failed'
+    });
+  }
+}
+
+function runExactSchemaValidator({ parsed, schemaId, resolution, schemaValidationAuthority = null }) {
+  const moduleId = resolution?.module?.id || '';
+  const validator = resolution?.module?.validate;
+  const exactRoot = !resolution?.fallbackUsed && (moduleId === 'tiinex.root.v1' || schemaId === 'tiinex.root.v1');
+  if (schemaValidationAuthority && schemaValidationAuthority.state !== 'qualified') return { ran: false, findings: [] };
+  if (exactRoot || resolution?.fallbackUsed || typeof validator !== 'function') return { ran: false, findings: [] };
+  return { ran: true, findings: normalizeFindings(validator(parsed), { schemaId: moduleId || schemaId, qualification: 'schema-specific' }) };
+}
+
+function fallbackFindingsFor({ schemaId, resolution, childFindings = [], childValidatorRan = false, machineContract = null }) {
+  const moduleId = resolution?.module?.id || '';
+  const exactRoot = !resolution?.fallbackUsed && (moduleId === 'tiinex.root.v1' || schemaId === 'tiinex.root.v1');
+  if (resolution?.fallbackUsed) return [
+    normalizeFinding({ ...rootFallbackFinding(schemaId), params: { field: 'Current Schema' } }, { schemaId: 'tiinex.root.v1', qualification: 'fallback' }),
+    normalizeFinding({ severity: 'warning', code: 'audit.validator.unavailable', message: `${schemaId || 'schema'} has no exact schema-specific validator; Root v1 validation was run instead.`, source: 'tiinex.audit.v1', qualification: 'validator-unavailable', params: { field: 'Current Schema' } })
+  ];
+  if (!exactRoot && !childValidatorRan && !machineContract?.available && machineContract?.reason !== 'schema-authority-unqualified') return [normalizeFinding({ severity: 'warning', code: 'audit.validator.unavailable', message: `${moduleId || schemaId || 'schema'} has no schema-specific validator and no qualified compiled machine contract; Root v1 validation was run instead.`, source: 'tiinex.audit.v1', qualification: 'validator-unavailable', params: { field: 'Current Schema' } })];
+  return [];
+}
+
+export function validationTruthFor({ parsed = null, schemaId = '', resolution = {}, childFindings = [], childValidatorRan = childFindings.length > 0, machineContract = null, findings = [], availability = { available: true }, supporting = false } = {}) {
+  const moduleId = resolution?.module?.id || '';
+  const schemaVersion = versionFromSchemaId(schemaId || moduleId);
+  const rootValidationVersion = 'tiinex.root.v1';
+  const integrityMethodVersions = integrityVersionsFor(parsed);
+  const proof = validationProofLevels({ parsed, machineContract, findings });
+  if (!availability?.available) return { state: 'not-run-body-unavailable', coverage: 'body-unavailable', rootValidator: 'not-run', childValidator: 'skipped', rootValidationVersion, childValidationVersion: schemaVersion, integrityMethodVersions, ...proof };
+  if (supporting) return { state: 'not-applicable-supporting', coverage: 'supporting-material', rootValidator: 'not-applicable', childValidator: 'not-applicable', rootValidationVersion, childValidationVersion: '', integrityMethodVersions, ...proof };
+  const fallbackUsed = Boolean(resolution?.fallbackUsed);
+  const exactRoot = !fallbackUsed && (moduleId === 'tiinex.root.v1' || schemaId === 'tiinex.root.v1');
+  const exactChildValidatorRan = !fallbackUsed && childValidatorRan && moduleId && moduleId !== 'tiinex.root.v1';
+  const childValidatorUnavailable = Boolean(schemaId) && !exactRoot && !exactChildValidatorRan;
+  if (exactChildValidatorRan) return { state: 'exact-schema-validated', coverage: machineContract?.available ? 'compiled-machine-contract+schema-companion' : 'schema-companion-without-compiled-contract', rootValidator: 'diagnostic', childValidator: 'run', rootValidationVersion, childValidationVersion: schemaVersion || moduleId, integrityMethodVersions, ...proof };
+  if (exactRoot) return { state: 'root-validated', coverage: machineContract?.available ? 'compiled-machine-contract' : 'root-readability-diagnostic', rootValidator: 'diagnostic', childValidator: 'not-applicable', rootValidationVersion, childValidationVersion: '', integrityMethodVersions, ...proof };
+  if (!fallbackUsed && !exactRoot && machineContract?.available && !exactChildValidatorRan) return { state: 'compiled-schema-validated', coverage: 'compiled-machine-contract', rootValidator: 'diagnostic', childValidator: 'compiled-contract', rootValidationVersion, childValidationVersion: schemaVersion || moduleId, integrityMethodVersions, ...proof };
+  if (childValidatorUnavailable) return { state: 'root-only-child-validator-unavailable', coverage: fallbackUsed ? 'root-fallback' : 'root-only', rootValidator: 'diagnostic', childValidator: 'unavailable', rootValidationVersion, childValidationVersion: schemaVersion || schemaId, integrityMethodVersions, ...proof };
+  return { state: 'validation-unknown', coverage: machineContract?.available ? 'compiled-machine-contract' : 'unknown', rootValidator: parsed ? 'diagnostic' : 'not-run', childValidator: 'unknown', rootValidationVersion, childValidationVersion: schemaVersion, integrityMethodVersions, ...proof };
+}
+
+function validationProofLevels({ parsed = null, machineContract = null, findings = [] } = {}) {
+  const parent = parsed?.envelope?.parent || {};
+  const parentDeclared = Boolean(parent?.schema?.id || parent?.trace || parent?.origin || parent?.createdAt || parent?.originEntries?.length);
+  const localContinuityReadable = parentDeclared ? Boolean(parent?.schema?.id && parent?.trace && (parent?.origin || parent?.originEntries?.length)) : true;
+  const semanticState = machineContract?.available ? String(machineContract.state || 'unresolved') : 'unavailable';
+  const integrityState = findings.some((finding) => finding.code === 'integrity.c14n-v2.mismatch' || finding.code === 'integrity.c14n-v2.ambiguous' || finding.code === 'integrity.method-reference.unqualified')
+    ? 'invalid-or-unverified'
+    : findings.some((finding) => finding.code === 'integrity.c14n-v2.verified') ? 'verified' : parsed?.hasIntegrity ? 'declared-unverified' : 'missing';
+  return Object.freeze({
+    readability: Object.freeze({ state: parsed?.hasContinuityContext ? 'readable' : 'incomplete' }),
+    localContinuity: Object.freeze({ state: parentDeclared ? (localContinuityReadable ? 'readable-local-continuity' : 'incomplete') : 'lineage-root' }),
+    semanticContract: Object.freeze({ state: semanticState, available: Boolean(machineContract?.available), schemaId: String(machineContract?.schemaId || ''), lineage: Object.freeze([...(machineContract?.lineage || [])]) }),
+    integrity: Object.freeze({ state: integrityState }),
+    exactCreationProof: Object.freeze({ state: 'not-evaluated-on-reopen' }),
+    exportReadiness: Object.freeze({ state: 'not-evaluated-on-reopen' })
+  });
+}
+
+function versionFromSchemaId(value = '') {
+  const text = String(value || '');
+  const match = text.match(/\.v(\d+)(?:\.|$)/);
+  return match ? `v${match[1]}` : '';
+}
+function integrityVersionsFor(parsed = null) {
+  const methods = Array.isArray(parsed?.integrity?.methods) ? parsed.integrity.methods : [];
+  return [...new Set(methods.map((method) => {
+    const text = String(method || '');
+    const match = text.match(/c14n-v(\d+)/i) || text.match(/-v(\d+)(?:\b|$)/i);
+    return match ? `v${match[1]}` : '';
+  }).filter(Boolean))];
+}

package/src/workspaces/workspace.entrypointCapability.js

@@ -0,0 +1,44 @@
+export const WORKSPACE_ARTIFACT_ROLE_SCHEMA = 'tiinex.workspace.artifact.role.v1';
+
+export function isWorkspaceEntrypointArtifact(record = {}) {
+  const path = recordPath(record);
+  if (isSchemaDefinitionPath(path)) return false;
+  if (isWorkspaceArtifactPath(path)) return true;
+  const role = record?.workspaceArtifactRole;
+  return Boolean(role && role.schema === WORKSPACE_ARTIFACT_ROLE_SCHEMA && (role.openEligible === true || role.mergeEligible === true));
+}
+
+export function workspaceEntrypointCapability(record = {}) {
+  const eligible = isWorkspaceEntrypointArtifact(record);
+  const role = record?.workspaceArtifactRole || {};
+  return Object.freeze({
+    schema: 'tiinex.workspace.entrypoint.capability.v1',
+    eligible,
+    open: Boolean(eligible && role.openEligible !== false),
+    merge: Boolean(eligible && role.mergeEligible !== false),
+    source: explicitWorkspaceArtifactRole(record) ? 'explicit-role' : (isWorkspaceArtifactPath(recordPath(record)) ? 'workspace-path' : 'none')
+  });
+}
+
+export function isWorkspaceArtifactPath(value = '') {
+  const path = String(value || '').trim().toLowerCase();
+  if (!path) return false;
+  return /(?:^|\/)[^/]+\.workspace(?:\s*\(\d+\))?\.md$/iu.test(path);
+}
+
+export function isSchemaDefinitionPath(value = '') {
+  const path = String(value || '').trim().toLowerCase();
+  return /(?:^|\/)[^/]+\.(?:schema|validator)\.md$/iu.test(path)
+    || path.includes('/schemas/')
+    || path.includes('/schema/')
+    || path.endsWith('schema.json');
+}
+
+function explicitWorkspaceArtifactRole(record = {}) {
+  const role = record?.workspaceArtifactRole;
+  return Boolean(role && role.schema === WORKSPACE_ARTIFACT_ROLE_SCHEMA && (role.openEligible === true || role.mergeEligible === true));
+}
+
+function recordPath(record = {}) {
+  return String(record.path || record.sourcePath || record.sourceTarget?.sourceArtifactPath || record.name || '').trim();
+}