@tiinex/core 0.1.1

package/src/governance/governance.boundary.js

@@ -0,0 +1,196 @@
+export const GOVERNANCE_BOUNDARY_SCHEMA_ID = 'tiinex.governance.boundary.v1';
+export const GOVERNANCE_SUMMARY_SCHEMA_ID = 'tiinex.governance.summary.v1';
+
+export const GOVERNANCE_POLICY_NAMES = Object.freeze([
+  'LINEAGE_LICENSE.md',
+  'LINEAGE_LICENSE',
+  'LINEAGE_POLICY.md',
+  'LINEAGE_POLICY',
+  'LICENSE.md',
+  'LICENSE',
+  'POLICY.md',
+  'POLICY'
+]);
+
+export const GOVERNANCE_NOTICE_NAMES = Object.freeze(['NOTICE', 'NOTICE.md']);
+
+const POLICY_NAME_RANK = Object.freeze(new Map(GOVERNANCE_POLICY_NAMES.map((name, index) => [name.toLowerCase(), index])));
+const NOTICE_NAME_RANK = Object.freeze(new Map(GOVERNANCE_NOTICE_NAMES.map((name, index) => [name.toLowerCase(), index])));
+
+export function isLineageGovernancePath(path = '') {
+  const root = governanceRootPath(path);
+  return /^LINEAGE_(LICENSE|POLICY)(\.md)?$/i.test(root);
+}
+
+export function isGovernancePolicyPath(path = '') {
+  const root = governanceRootPath(path);
+  return POLICY_NAME_RANK.has(root.toLowerCase());
+}
+
+export function isGovernanceNoticePath(path = '') {
+  const root = governanceRootPath(path);
+  return NOTICE_NAME_RANK.has(root.toLowerCase());
+}
+
+export function governanceRootPath(path = '') {
+  const clean = sourceArtifactPath(path).replace(/^\/+/, '').replace(/\\/g, '/').replace(/\/+/g, '/');
+  if (!clean || clean.includes('/')) return '';
+  return clean;
+}
+
+export function governanceBoundaryFromRootFiles(source = {}, files = [], input = {}) {
+  const normalizedFiles = normalizeGovernanceFiles(files);
+  const policy = firstRankedFile(normalizedFiles.filter((file) => file.type === 'policy'), POLICY_NAME_RANK);
+  const notice = firstRankedFile(normalizedFiles.filter((file) => file.type === 'notice'), NOTICE_NAME_RANK);
+  return buildGovernanceBoundary(source, { policy, notice, rootChecked: input.rootChecked === true, discoveredFrom: input.discoveredFrom || '' });
+}
+
+export function buildGovernanceBoundaryForSource(source = {}, input = {}) {
+  const entries = [];
+  for (const record of input.records || []) entries.push(governanceFileFromMaterial(record));
+  for (const asset of input.assets || []) entries.push(governanceFileFromMaterial(asset));
+  return governanceBoundaryFromRootFiles(source, entries.filter(Boolean), { rootChecked: input.rootChecked === true, discoveredFrom: input.discoveredFrom || 'loaded-source-material' });
+}
+
+export function buildWorkspaceGovernanceSummary(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const assets = Array.isArray(input.assets) ? input.assets : (Array.isArray(workspace.assets) ? workspace.assets : []);
+  const sources = Array.isArray(workspace.sources) ? workspace.sources : [];
+  const sourceBoundaries = sources
+    .filter((source) => isSourceBacked(source))
+    .map((source) => source.governanceBoundary?.schema === GOVERNANCE_BOUNDARY_SCHEMA_ID
+      ? source.governanceBoundary
+      : buildGovernanceBoundaryForSource(source, { records: records.filter((record) => String(record?.source?.id || '') === String(source.id || '')), assets: assets.filter((asset) => String(asset?.source?.id || '') === String(source.id || '')) }))
+    .filter(Boolean);
+  const counts = {
+    sources: sourceBoundaries.length,
+    found: sourceBoundaries.filter((item) => item.status === 'found').length,
+    originFallback: sourceBoundaries.filter((item) => item.status === 'origin-fallback').length,
+    missing: sourceBoundaries.filter((item) => item.status === 'missing').length,
+    unknown: sourceBoundaries.filter((item) => item.status === 'unknown').length,
+    local: sourceBoundaries.filter((item) => item.status === 'local').length,
+    notices: sourceBoundaries.filter((item) => item.notice?.status === 'found').length
+  };
+  const status = counts.missing ? 'degraded' : (counts.unknown ? 'unknown' : (counts.found || counts.originFallback || counts.notices ? 'ready' : 'local'));
+  return deepFreeze({
+    schema: GOVERNANCE_SUMMARY_SCHEMA_ID,
+    status,
+    boundary: 'Governance summary carries source/root policy, license, and notice context. It is advisory metadata for transitions/export and does not mutate source material.',
+    counts: Object.freeze(counts),
+    sources: Object.freeze(sourceBoundaries)
+  });
+}
+
+export function governanceFindingForBoundary(boundary = {}, input = {}) {
+  if (!boundary || boundary.schema !== GOVERNANCE_BOUNDARY_SCHEMA_ID) return null;
+  const repo = boundary.scope?.repo || input.repo || '';
+  if (boundary.status === 'missing') return finding('warning', 'governance.boundary.missing', `No lineage policy/license file was found at the origin root for ${repo || 'this source'}.`, { repo, status: boundary.status });
+  if (boundary.status === 'unknown') return finding('info', 'governance.boundary.unknown', `Governance boundary for ${repo || 'this source'} was not checked in this bounded materialization.`, { repo, status: boundary.status });
+  if (boundary.status === 'found' || boundary.status === 'origin-fallback') return finding('info', 'governance.boundary.detected', `${boundary.policy?.kind || 'Governance file'} applies to source-backed material from ${repo || 'this source'}.`, { repo, status: boundary.status, kind: boundary.policy?.kind || '' });
+  return null;
+}
+
+function buildGovernanceBoundary(source = {}, input = {}) {
+  const repo = normalizeRepo(source.repo || source.repository || source.config?.repo || '');
+  const ref = String(source.ref || source.config?.ref || '').trim();
+  const policy = input.policy || null;
+  const noticeFile = input.notice || null;
+  if (!repo) {
+    return deepFreeze({
+      schema: GOVERNANCE_BOUNDARY_SCHEMA_ID,
+      status: 'local',
+      scope: Object.freeze({ kind: 'local', repo: '', ref: '', root: '' }),
+      policy: null,
+      notice: Object.freeze({ status: 'local', kind: '', path: '', url: '', note: 'Local/browser material has no remote origin governance lookup.' }),
+      rootChecked: false,
+      boundary: 'Local/browser workspace material does not inherit GitHub repository governance by inference.'
+    });
+  }
+  const status = policy ? (isLineageGovernancePath(policy.path || policy.kind) ? 'found' : 'origin-fallback') : (input.rootChecked ? 'missing' : 'unknown');
+  return deepFreeze({
+    schema: GOVERNANCE_BOUNDARY_SCHEMA_ID,
+    status,
+    scope: Object.freeze({ kind: 'github-repo-root', repo, ref, root: '/' }),
+    policy: policy ? Object.freeze({ kind: policy.kind || governanceRootPath(policy.path), path: policy.path || policy.kind || '', url: policy.url || repoRawUrl(repo, ref, policy.path || policy.kind || ''), contentAvailable: Boolean(policy.text || policy.content || policy.body) }) : null,
+    notice: noticeFile ? Object.freeze({ status: 'found', kind: noticeFile.kind || governanceRootPath(noticeFile.path), path: noticeFile.path || noticeFile.kind || '', url: noticeFile.url || repoRawUrl(repo, ref, noticeFile.path || noticeFile.kind || ''), contentAvailable: Boolean(noticeFile.text || noticeFile.content || noticeFile.body), note: 'NOTICE found at source root.' }) : Object.freeze({ status: input.rootChecked ? 'missing' : 'unknown', kind: '', path: '', url: '', note: input.rootChecked ? 'No NOTICE file found at source root.' : 'Root NOTICE was not checked in this bounded materialization.' }),
+    rootChecked: input.rootChecked === true,
+    discoveredFrom: input.discoveredFrom || '',
+    candidates: Object.freeze({ policy: GOVERNANCE_POLICY_NAMES.slice(), notice: GOVERNANCE_NOTICE_NAMES.slice() }),
+    note: status === 'missing'
+      ? `No lineage policy/license found at ${repo}@${ref || 'unresolved'} root. Checked known root names only.`
+      : status === 'unknown'
+        ? `Governance root files for ${repo}@${ref || 'unresolved'} were not checked by this bounded materialization.`
+        : `${policy?.kind || governanceRootPath(policy?.path || '')} applies to source-backed material from ${repo}@${ref || 'unresolved'}.`,
+    boundary: 'Governance boundary follows explicit source origin root files only. README/validation notes are not treated as license/policy fallback.'
+  });
+}
+
+function normalizeGovernanceFiles(files = []) {
+  return (files || []).map((file) => {
+    const path = governanceRootPath(file?.path || file?.kind || file?.name || '');
+    if (!path) return null;
+    const lower = path.toLowerCase();
+    const kind = POLICY_NAME_RANK.has(lower) ? 'policy' : NOTICE_NAME_RANK.has(lower) ? 'notice' : '';
+    if (!kind) return null;
+    return Object.assign({}, file, { path, kind: file.kind || path, governanceKind: kind });
+  }).filter(Boolean).map((file) => Object.assign({}, file, { kind: file.path, type: file.governanceKind }));
+}
+
+function firstRankedFile(files = [], rankMap = new Map()) {
+  return files.slice().sort((a, b) => (rankMap.get(String(a.path || a.kind || '').toLowerCase()) ?? 999) - (rankMap.get(String(b.path || b.kind || '').toLowerCase()) ?? 999))[0] || null;
+}
+
+function governanceFileFromMaterial(item = {}) {
+  const path = governanceRootPath(item?.sourceTarget?.sourceArtifactPath || item?.path || item?.name || '');
+  if (!path) return null;
+  if (!isGovernancePolicyPath(path) && !isGovernanceNoticePath(path)) return null;
+  return {
+    path,
+    kind: path,
+    url: item?.sourceTarget?.rawUrl || item?.source?.url || '',
+    text: item?.markdown || item?.content || item?.text || ''
+  };
+}
+
+function sourceArtifactPath(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    if (/raw\.githubusercontent\.com$/i.test(url.hostname)) {
+      const parts = url.pathname.split('/').filter(Boolean);
+      if (parts.length >= 4) return parts.slice(3).join('/');
+    }
+    if (/github\.com$/i.test(url.hostname) && /\/blob\//i.test(url.pathname)) {
+      const parts = url.pathname.split('/').filter(Boolean);
+      const blob = parts.indexOf('blob');
+      if (blob >= 0) return parts.slice(blob + 2).join('/');
+    }
+  } catch (_) {}
+  return raw;
+}
+
+function normalizeRepo(value = '') {
+  return String(value || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '').split('/').slice(0, 2).join('/');
+}
+
+function repoRawUrl(repo = '', ref = '', path = '') {
+  if (!repo || !ref || !path) return '';
+  return `https://raw.githubusercontent.com/${repo}/${encodeURIComponent(ref)}/${String(path).split('/').map((part) => encodeURIComponent(part)).join('/')}`;
+}
+
+function isSourceBacked(source = {}) {
+  const kind = String(source.adapterId || source.sourceKind || source.kind || '').toLowerCase();
+  return kind.includes('github') || kind.includes('source');
+}
+
+function finding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra || {}));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const item of Object.values(value)) deepFreeze(item);
+  return value;
+}

package/src/integrity/integrity.c14nV2.js

@@ -0,0 +1,190 @@
+export const C14N_V2_METHOD_ID = 'sha256-base64url-c14n-v2';
+
+export function canonicalC14nV2SelfState(markdown = '') {
+  const normalized = normalizeCanonicalSource(markdown);
+  const located = locateSelfEntries(normalized);
+  if (located.integrityHeading < 0) return Object.freeze({ state: 'unavailable', reason: 'integrity-footer-missing', entries: Object.freeze([]) });
+  if (located.entries.length !== 1) return Object.freeze({ state: 'ambiguous', reason: located.entries.length ? 'multiple-primary-self-entries' : 'primary-self-entry-missing', entries: Object.freeze(located.entries) });
+  const entry = located.entries[0];
+  if (entry.valueLines.length !== 1) return Object.freeze({ state: 'ambiguous', reason: entry.valueLines.length ? 'multiple-value-fields' : 'value-field-missing', entries: Object.freeze(located.entries) });
+  const valueLine = entry.valueLines[0];
+  const canonicalLines = located.lines.slice();
+  canonicalLines[valueLine.index] = `${valueLine.label}${valueLine.spacing}`;
+  const canonical = canonicalLines.join('\n');
+  const computedValue = sha256Base64Url(canonical);
+  const declaredValue = valueLine.value;
+  return Object.freeze({
+    state: declaredValue && declaredValue === computedValue ? 'verified' : declaredValue ? 'mismatch' : 'prepared',
+    reason: declaredValue && declaredValue !== computedValue ? 'digest-mismatch' : '',
+    method: C14N_V2_METHOD_ID,
+    towards: 'self',
+    declaredValue,
+    computedValue,
+    canonical,
+    entryIndex: entry.entryIndex,
+    valueLineIndex: valueLine.index
+  });
+}
+
+
+export function validatedC14nV2PrimarySelfDigest(markdown = '') {
+  const state = canonicalC14nV2SelfState(markdown);
+  if (state.state !== 'verified') return Object.freeze({
+    state: state.state,
+    reason: state.reason || state.state,
+    value: '',
+    declaredValue: state.declaredValue || '',
+    computedValue: state.computedValue || ''
+  });
+  return Object.freeze({
+    state: 'verified',
+    reason: '',
+    value: state.declaredValue,
+    declaredValue: state.declaredValue,
+    computedValue: state.computedValue
+  });
+}
+
+export function verifyC14nV2TargetSelfDigest({ value = '', targetMarkdown = '' } = {}) {
+  const expectedValue = String(value || '').trim();
+  const target = validatedC14nV2PrimarySelfDigest(targetMarkdown);
+  if (target.state !== 'verified') return Object.freeze({
+    state: target.state === 'mismatch' ? 'target-self-mismatch' : target.state,
+    reason: target.reason || target.state,
+    expectedValue,
+    targetValue: target.declaredValue || '',
+    computedTargetValue: target.computedValue || ''
+  });
+  return Object.freeze({
+    state: expectedValue && expectedValue === target.value ? 'verified' : 'mismatch',
+    reason: !expectedValue ? 'comparison-value-missing' : expectedValue === target.value ? '' : 'target-self-digest-mismatch',
+    expectedValue,
+    targetValue: target.value,
+    computedTargetValue: target.computedValue
+  });
+}
+
+export function sealC14nV2Self(markdown = '') {
+  const state = canonicalC14nV2SelfState(markdown);
+  if (!['verified', 'mismatch', 'prepared'].includes(state.state)) return Object.freeze({ state: state.state, reason: state.reason, markdown: String(markdown || ''), value: '' });
+  const normalized = normalizeCanonicalSource(markdown);
+  const lines = normalized.split('\n');
+  const located = locateSelfEntries(normalized);
+  const valueLine = located.entries[0]?.valueLines?.[0];
+  if (!valueLine) return Object.freeze({ state: 'ambiguous', reason: 'value-field-missing', markdown: String(markdown || ''), value: '' });
+  lines[valueLine.index] = `${valueLine.label}${valueLine.spacing}${state.computedValue}`;
+  return Object.freeze({ state: 'sealed', reason: '', markdown: lines.join('\n'), value: state.computedValue });
+}
+
+export function sha256Base64Url(text = '') {
+  return base64Url(sha256Bytes(new TextEncoder().encode(String(text || ''))));
+}
+
+function normalizeCanonicalSource(markdown = '') {
+  return String(markdown || '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t]+$/gm, '')
+    .trimEnd();
+}
+
+function locateSelfEntries(normalized = '') {
+  const lines = String(normalized || '').split('\n');
+  const integrityHeading = lines.findIndex((line) => line === '# Continuity Integrity');
+  if (integrityHeading < 0) return { lines, integrityHeading, entries: [] };
+  const allEntries = [];
+  let current = null;
+  const finish = (end) => {
+    if (!current) return;
+    current.end = end;
+    allEntries.push(current);
+    current = null;
+  };
+  for (let index = integrityHeading + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^#\s+/.test(line)) { finish(index); break; }
+    const top = line.match(/^-\s+(.+?)\s*$/);
+    if (top) {
+      finish(index);
+      current = { entryIndex: allEntries.length, start: index, end: lines.length, method: stripMarkdownLink(top[1].trim()), towards: '', valueLines: [] };
+      continue;
+    }
+    if (!current) continue;
+    const towards = line.match(/^\s+-\s+Towards:\s*(.*?)\s*$/);
+    if (towards) current.towards = stripMarkdownLink(towards[1].trim());
+    const value = line.match(/^(\s+-\s+Value:)([ \t]*)(.*)$/);
+    if (value) current.valueLines.push({ index, label: value[1], spacing: value[2], value: value[3].trim() });
+  }
+  finish(lines.length);
+  const entries = allEntries.filter((entry) => entry.method === C14N_V2_METHOD_ID && entry.towards === 'self');
+  return { lines, integrityHeading, entries };
+}
+
+function stripMarkdownLink(value = '') {
+  const text = String(value || '').trim();
+  const link = text.match(/^\[([^\]]+)\]\([^)]+\)$/);
+  return (link ? link[1] : text).trim();
+}
+
+function sha256Bytes(bytes) {
+  const K = [
+    0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+    0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+    0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+    0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+    0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+    0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+    0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+    0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2
+  ];
+  const length = bytes.length;
+  const bitLength = length * 8;
+  const paddedLength = (((length + 9 + 63) >> 6) << 6);
+  const buffer = new Uint8Array(paddedLength);
+  buffer.set(bytes);
+  buffer[length] = 0x80;
+  const view = new DataView(buffer.buffer);
+  const high = Math.floor(bitLength / 0x100000000);
+  const low = bitLength >>> 0;
+  view.setUint32(paddedLength - 8, high, false);
+  view.setUint32(paddedLength - 4, low, false);
+  let h0=0x6a09e667,h1=0xbb67ae85,h2=0x3c6ef372,h3=0xa54ff53a,h4=0x510e527f,h5=0x9b05688c,h6=0x1f83d9ab,h7=0x5be0cd19;
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = view.getUint32(offset + i * 4, false);
+    for (let i = 16; i < 64; i += 1) {
+      const a=w[i-15], b=w[i-2];
+      const s0=(rotr(a,7)^rotr(a,18)^(a>>>3))>>>0;
+      const s1=(rotr(b,17)^rotr(b,19)^(b>>>10))>>>0;
+      w[i]=(w[i-16]+s0+w[i-7]+s1)>>>0;
+    }
+    let a=h0,b=h1,c=h2,d=h3,e=h4,f=h5,g=h6,h=h7;
+    for (let i=0;i<64;i+=1) {
+      const S1=(rotr(e,6)^rotr(e,11)^rotr(e,25))>>>0;
+      const ch=((e&f)^(~e&g))>>>0;
+      const t1=(h+S1+ch+K[i]+w[i])>>>0;
+      const S0=(rotr(a,2)^rotr(a,13)^rotr(a,22))>>>0;
+      const maj=((a&b)^(a&c)^(b&c))>>>0;
+      const t2=(S0+maj)>>>0;
+      h=g; g=f; f=e; e=(d+t1)>>>0; d=c; c=b; b=a; a=(t1+t2)>>>0;
+    }
+    h0=(h0+a)>>>0; h1=(h1+b)>>>0; h2=(h2+c)>>>0; h3=(h3+d)>>>0;
+    h4=(h4+e)>>>0; h5=(h5+f)>>>0; h6=(h6+g)>>>0; h7=(h7+h)>>>0;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  [h0,h1,h2,h3,h4,h5,h6,h7].forEach((value,index)=>outView.setUint32(index*4,value,false));
+  return out;
+}
+function rotr(value, shift) { return ((value >>> shift) | (value << (32 - shift))) >>> 0; }
+function base64Url(bytes) {
+  const alphabet='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  let out='';
+  for (let i=0;i<bytes.length;i+=3) {
+    const a=bytes[i], b=i+1<bytes.length?bytes[i+1]:0, c=i+2<bytes.length?bytes[i+2]:0;
+    const triple=(a<<16)|(b<<8)|c;
+    out+=alphabet[(triple>>>18)&63]+alphabet[(triple>>>12)&63];
+    if (i+1<bytes.length) out+=alphabet[(triple>>>6)&63];
+    if (i+2<bytes.length) out+=alphabet[triple&63];
+  }
+  return out;
+}

package/src/integrity/integrity.methodReference.js

@@ -0,0 +1,73 @@
+export const INTEGRITY_METHOD_REFERENCE_AUTHORITY_SCHEMA_ID = 'tiinex.site.integrity-method-reference-authority.v1';
+export const C14N_V2_METHOD_ID = 'sha256-base64url-c14n-v2';
+export const C14N_V2_VALIDATOR_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.validators/sha256-base64url-c14n-v2.validator.md';
+const C14N_V2_PRIOR_EQUIVALENT_TARGET = 'https://github.com/Tiinex/docs/blob/053d46ce082d4ec261b82abc44ecca403d61e240/.topics/.validators/sha256-base64url-c14n-v2.validator.md';
+
+const maintainedC14nV2 = Object.freeze({
+  schema: INTEGRITY_METHOD_REFERENCE_AUTHORITY_SCHEMA_ID,
+  methodId: C14N_V2_METHOD_ID,
+  preferredTarget: C14N_V2_VALIDATOR_TARGET,
+  exactTargets: Object.freeze([C14N_V2_VALIDATOR_TARGET, C14N_V2_PRIOR_EQUIVALENT_TARGET]),
+  resolutionState: 'qualified',
+  resolutionEvidence: Object.freeze({
+    sourceRepository: 'Tiinex/docs',
+    sourceCommit: '3988951208eb9a8926e84ab42625d4b42fa00c2d',
+    sourcePath: '.topics/.validators/sha256-base64url-c14n-v2.validator.md',
+    gitBlobSha: '20df4285e96a26ba69e9b8c054688cfdb60492d3'
+  })
+});
+
+export function integrityMethodReferenceAuthorityForCreation(methodId = C14N_V2_METHOD_ID, explicit = undefined) {
+  const id = String(methodId || '').trim();
+  const fallback = id === C14N_V2_METHOD_ID ? maintainedC14nV2 : Object.freeze({
+    schema: INTEGRITY_METHOD_REFERENCE_AUTHORITY_SCHEMA_ID,
+    methodId: id,
+    preferredTarget: '',
+    exactTargets: Object.freeze([]),
+    resolutionState: 'unavailable',
+    resolutionEvidence: Object.freeze({})
+  });
+  if (explicit === undefined || explicit === null) return fallback;
+  if (explicit === false) return Object.freeze({ ...fallback, preferredTarget: '', exactTargets: Object.freeze([]), resolutionState: 'unavailable', resolutionEvidence: Object.freeze({}) });
+  if (typeof explicit === 'string') return Object.freeze({ ...fallback, preferredTarget: explicit, exactTargets: Object.freeze(explicit ? [explicit] : []), resolutionState: 'unresolved', resolutionEvidence: Object.freeze({}) });
+  const target = String(explicit.preferredTarget || explicit.target || '').trim();
+  const exactTargets = Object.freeze([...new Set([...(explicit.exactTargets || []), target].map((item) => String(item || '')).filter(Boolean))]);
+  return Object.freeze({
+    ...fallback,
+    methodId: String(explicit.methodId || id),
+    preferredTarget: target || exactTargets[0] || '',
+    exactTargets,
+    resolutionState: String(explicit.resolutionState || explicit.state || (target && fallback.exactTargets.includes(target) ? fallback.resolutionState : 'unresolved')),
+    resolutionEvidence: Object.freeze({ ...(target && fallback.exactTargets.includes(target) ? fallback.resolutionEvidence : {}), ...(explicit.resolutionEvidence || explicit.evidence || {}) })
+  });
+}
+
+export function renderIntegrityMethodReference(authority = {}) {
+  const methodId = String(authority?.methodId || '').trim();
+  if (!methodId) throw new Error('integrity-method-reference-id-missing');
+  const target = authority?.resolutionState === 'qualified' ? String(authority?.preferredTarget || '').trim() : '';
+  return target ? `[${methodId}](${target})` : methodId;
+}
+
+export function qualifyIntegrityMethodReferenceValue(value = '', authority = {}) {
+  const raw = String(value || '').trim();
+  const parsed = parseMethodReference(raw);
+  const methodId = String(authority?.methodId || '').trim();
+  const exactTargets = new Set([...(authority?.exactTargets || [])].map((item) => String(item || '')).filter(Boolean));
+  const maintainedAvailable = authority?.resolutionState === 'qualified' && Boolean(authority?.preferredTarget);
+  const findings = [];
+  if (!methodId || parsed.methodId !== methodId) findings.push(`Integrity method identifier must be exactly ${methodId || '(unavailable)'}.`);
+  if (maintainedAvailable) {
+    if (parsed.form === 'markdown-link' && !exactTargets.has(parsed.target)) findings.push(`Integrity method target is not the qualified maintained representation for ${methodId}: ${parsed.target || '(empty)'}.`);
+  } else if (parsed.form === 'markdown-link' && exactTargets.size && !exactTargets.has(parsed.target)) {
+    findings.push(`Integrity method target is not qualified for ${methodId}: ${parsed.target || '(empty)'}.`);
+  }
+  return Object.freeze({ state: findings.length ? 'unavailable' : 'qualified', observed: parsed, authority, maintainedTargetAvailable: maintainedAvailable, findings: Object.freeze(findings) });
+}
+
+function parseMethodReference(value = '') {
+  const text = String(value || '').trim();
+  const match = text.match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  if (match) return Object.freeze({ raw: text, form: 'markdown-link', methodId: match[1], target: match[2] });
+  return Object.freeze({ raw: text, form: text ? 'plain-method-id' : 'empty', methodId: text, target: '' });
+}

package/src/integrity/integrity.validate.js

@@ -0,0 +1,56 @@
+import { C14N_V2_METHOD_ID, canonicalC14nV2SelfState } from './integrity.c14nV2.js';
+import { integrityMethodReferenceAuthorityForCreation, qualifyIntegrityMethodReferenceValue } from './integrity.methodReference.js';
+
+export const INTEGRITY_VALIDATION_ENGINE_ID = 'tiinex.integrity.validation.v1';
+
+export function validateIntegrity(artifact = {}, options = {}) {
+  const findings = [];
+  const methods = normalizeMethods(artifact?.integrity?.methods);
+  const hasIntegrity = Boolean(artifact?.hasIntegrity);
+
+  if (!hasIntegrity) {
+    findings.push(info('integrity.validation.skipped', 'Continuity Integrity footer is missing; integrity engine did not run byte/canonicalization validation.'));
+    return findings;
+  }
+
+  if (!methods.length) {
+    findings.push(info('integrity.method.unspecified', 'Continuity Integrity exists but no machine-verifiable integrity method is declared.'));
+    return findings;
+  }
+
+  if (methods.includes(C14N_V2_METHOD_ID)) {
+    findings.push(info('integrity.c14n-v2.detected', 'c14n-v2 integrity method is declared; the integrity engine evaluates self entries when canonical artifact bytes are available.'));
+    const selfEntries = (artifact?.integrity?.entries || []).filter((entry) => entry?.method === C14N_V2_METHOD_ID && entry?.towards === 'self');
+    const maintainedAuthority = integrityMethodReferenceAuthorityForCreation(C14N_V2_METHOD_ID);
+    for (const entry of (artifact?.integrity?.entries || []).filter((item) => item?.method === C14N_V2_METHOD_ID)) {
+      const reference = qualifyIntegrityMethodReferenceValue(entry?.methodRaw || entry?.method || '', maintainedAuthority);
+      if (reference.state !== 'qualified') findings.push(error('integrity.method-reference.unqualified', reference.findings.join(' ')));
+      else findings.push(info('integrity.method-reference.qualified', 'c14n-v2 integrity method reference conforms to the canonical Root method-entry contract.'));
+    }
+    if (selfEntries.length) {
+      const result = canonicalC14nV2SelfState(artifact.markdown || '');
+      if (result.state === 'verified') findings.push(info('integrity.c14n-v2.verified', 'c14n-v2 self-integrity is verified against the current canonical artifact bytes.'));
+      else if (result.state === 'mismatch') findings.push(warning('integrity.c14n-v2.mismatch', 'c14n-v2 self-integrity does not match the current canonical artifact bytes.'));
+      else findings.push(warning('integrity.c14n-v2.ambiguous', `c14n-v2 self-integrity could not be verified: ${result.reason || result.state}.`));
+    }
+  }
+
+  for (const method of methods) {
+    if (method === C14N_V2_METHOD_ID) continue;
+    if (/browser-local-draft|draft local integrity/i.test(method)) {
+      findings.push(info('integrity.local-draft.declared', 'Draft/local integrity marker is present; it is a recoverability marker, not a published byte-verification proof.'));
+      continue;
+    }
+    findings.push(info('integrity.method.declared', `Integrity method declared: ${method}.`));
+  }
+  return findings;
+}
+
+function normalizeMethods(methods = []) {
+  if (!Array.isArray(methods)) return [];
+  return [...new Set(methods.map((method) => String(method || '').trim()).filter(Boolean))];
+}
+
+function warning(code, message) { return { severity: 'warning', code, message, source: INTEGRITY_VALIDATION_ENGINE_ID }; }
+function info(code, message) { return { severity: 'info', code, message, source: INTEGRITY_VALIDATION_ENGINE_ID }; }
+function error(code, message) { return { severity: 'error', code, message, source: INTEGRITY_VALIDATION_ENGINE_ID }; }

package/src/lineage/lineage.candidateResolution.js

@@ -0,0 +1,46 @@
+import { lineageBasePathForNode } from './lineage.pathBasis.js';
+import { preferredLineageMaterialCandidates } from './lineage.materialPreference.js';
+import { canonicalPath } from './lineage.targetKeys.js';
+
+export function resolveCandidateNodes(nodes = [], method = 'unknown', declaringNode = null) {
+  const unique = uniqueNodes(nodes || []);
+  if (!unique.length) return null;
+  const withoutSelf = unique.filter((candidate) => !sameLineageNode(candidate, declaringNode));
+  if (!withoutSelf.length) return { selfReference: true, method, candidates: unique };
+  const preferred = preferredLineageMaterialCandidates(withoutSelf, method);
+  if (preferred.length === 1) return Object.assign({ method }, preferred[0]);
+  if (withoutSelf.length === 1) return Object.assign({ method }, withoutSelf[0]);
+  return { ambiguous: true, method, candidates: preferred.length ? preferred : withoutSelf };
+}
+
+export function relativeCandidatePath(rawTarget, declaringNode = null) {
+  const raw = String(rawTarget || '').trim();
+  const declaringPath = canonicalPath(lineageBasePathForNode(declaringNode));
+  const targetPath = canonicalPath(raw);
+  if (!targetPath) return null;
+  const dir = dirname(declaringPath);
+  return { path: normalizeJoinedPath(dir, raw), method: dir ? 'relative-path' : 'relative-root-path' };
+}
+
+export function isSimpleRelativeReference(value = '') {
+  const raw = String(value || '').trim();
+  const path = canonicalPath(raw);
+  return Boolean(raw && path && !path.includes('/') && !isUrlLike(raw) && !/^record:/i.test(raw));
+}
+
+export function isDotRelativeReference(value = '') { return /^\.\.?(?:\/|$)/.test(String(value || '').replace(/\\/g, '/').trim()); }
+
+function sameLineageNode(candidate = {}, declaringNode = null) {
+  if (!candidate || !declaringNode) return false;
+  const candidateId = String(candidate.id || '').trim();
+  const declaringId = String(declaringNode.id || '').trim();
+  if (candidateId && declaringId) return candidateId === declaringId;
+  const candidatePath = canonicalPath(candidate.path || candidate.record?.path || '');
+  const declaringPath = canonicalPath(declaringNode.path || declaringNode.record?.path || '');
+  return Boolean(candidatePath && declaringPath && candidatePath === declaringPath);
+}
+
+function dirname(path = '') { const parts = canonicalPath(path).split('/').filter(Boolean); parts.pop(); return parts.join('/'); }
+function normalizeJoinedPath(base = '', target = '') { const text = String(target || '').replace(/\\/g, '/'); return canonicalPath(text.startsWith('/') ? text : [base, text].filter(Boolean).join('/')); }
+export function isUrlLike(value = '') { return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(String(value || '').trim()); }
+function uniqueNodes(nodes = []) { const seen = new Set(); const out = []; for (const node of Array.isArray(nodes) ? nodes : []) { const key = node?.id || node?.path || JSON.stringify(node || {}); if (!key || seen.has(key)) continue; seen.add(key); out.push(node); } return out; }