@tiinex/app 0.1.1

package/src/app/schemaNavigationCommand.js

@@ -0,0 +1,285 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { parseArtifactMarkdown } from '@tiinex/core/artifacts/artifact.parse.js';
+import { schemaCatalogEntryForId, schemaFilenameForId, schemaMarkdownCatalog } from '../schemas/schemaMarkdownCatalog.js';
+import { declaredSchemaRecoveryTarget, qualifySchemaRecordRecoveryRepresentation, recoverDeclaredSchemaEntry, schemaRecoveryRepresentationIdentity } from './schemaSourceRecovery.js';
+import { qualifySchemaReadingContractMarkdown } from './schemaReadingContractQualification.js';
+import { normalizeExplicitFileRefs } from '@tiinex/core/sources/source.explicitTargets.js';
+import { isSchemaDefinitionPath } from '@tiinex/core/workspaces/workspace.entrypointCapability.js';
+import { qualifyRecordCurrentSchemaDeclaration } from './schemaCurrentDeclaration.js';
+import { focusSchemaRecordState, stateWithWorkspaceStructuralCopy } from './schemaNavigationState.js';
+import { coalesceRecoveredGithubSchemaSource, qualifySchemaMaterializationReuse } from './schemaNavigationMaterialization.js';
+
+const SCHEMA_SOURCE_ID = 'viewer-schema-registry';
+const SCHEMA_SOURCE_LABEL = 'Viewer schema registry';
+const SCHEMA_SOURCE_BOUNDARY = 'bundled viewer schema reading contract; not user-local material and not guessed GitHub provenance';
+
+export async function openSchemaForRecordCommand(input = {}) {
+  const state = input.state;
+  const workspace = input.workspace || workspaceById(state, input.workspaceId || state?.activeWorkspaceId);
+  if (!workspace) return { ok: false, error: 'workspace.missing', state, notice: 'No active workspace is available.' };
+  const record = input.record || recordById(workspace, input.recordId || state?.view?.selectedRecordId || '');
+  const explicitSchemaId = normalizeSchemaId(input.schemaId || '');
+  const declaration = qualifyRecordCurrentSchemaDeclaration(record, explicitSchemaId);
+  if (declaration.materialState === 'concrete' && declaration.state !== 'qualified') {
+    const error = declaration.state === 'ambiguous' ? 'schema.declaration.ambiguous' : (declaration.state === 'mismatch' ? 'schema.declaration.mismatch' : 'schema.declaration.unavailable');
+    return { ok: false, error, state, schemaId: explicitSchemaId || normalizeSchemaId(recordSchemaId(record)), declaration, notice: 'This artifact does not provide one exact Current Schema declaration that can authorize Open Schema.' };
+  }
+  if (declaration.materialState === 'read-failed') return { ok: false, error: 'schema.declaration.unavailable', state, declaration, notice: 'This artifact\'s concrete Current Schema declaration could not be read.' };
+  const schemaId = declaration.state === 'qualified' ? declaration.schemaId : (explicitSchemaId || normalizeSchemaId(recordSchemaId(record)));
+  if (!schemaId || schemaId === 'plain' || schemaId === 'markdown' || schemaId === 'unknown') return { ok: false, error: 'schema.missing', state, declaration, notice: 'This artifact does not declare an openable reading contract schema.' };
+
+  const linkedDeclaration = declaration.state === 'qualified' && Boolean(declaration.target);
+  const declaredTarget = linkedDeclaration ? declaredSchemaRecoveryTarget(record, schemaId) : null;
+  const representationIdentity = linkedDeclaration && declaredTarget?.ok ? schemaRecoveryRepresentationIdentity(declaredTarget) : '';
+  if (linkedDeclaration && (!declaredTarget?.ok || !representationIdentity)) {
+    return { ok: false, error: 'schema.unavailable', state, schemaId, declaration, recovery: declaredTarget, notice: `Reading contract schema ${schemaId} is unavailable because its declared representation target cannot be qualified.` };
+  }
+
+  const loadedQualification = qualifyLoadedSchemaRecords(workspace, schemaId, representationIdentity);
+  if (loadedQualification.state === 'ambiguous') return { ok: false, error: 'schema.ambiguous', state, schemaId, notice: `Multiple qualified reading contracts are loaded for ${schemaId}; exact selection authority is unavailable.` };
+  const existing = loadedQualification.record || null;
+  if (existing) return focusSchemaRecordState({ state, workspaceId: workspace.id, record: existing, schemaId, notice: `Opened reading contract: ${schemaShortLabel(schemaId)}.`, existing: true });
+
+  let recovered = null;
+  if (linkedDeclaration) {
+    recovered = await recoverDeclaredSchemaEntry({ record, schemaId, fetchImpl: input.fetchImpl });
+    if (!recovered?.ok) return { ok: false, error: 'schema.unavailable', state, schemaId, declaration, recovery: recovered, notice: `Reading contract schema ${schemaId} is unavailable because its declared representation could not be recovered and qualified.` };
+  } else if (!input.schemaEntry) recovered = await recoverDeclaredSchemaEntry({ record, schemaId, fetchImpl: input.fetchImpl });
+  const catalog = input.catalog || schemaMarkdownCatalog;
+  let entry = linkedDeclaration ? recovered : (input.schemaEntry || (recovered?.ok ? recovered : null) || (catalog?.[schemaId] || schemaCatalogEntryForId(schemaId)));
+  if (entry && !entry.markdown && typeof input.loadSchemaMarkdown === 'function') {
+    try { entry = await input.loadSchemaMarkdown(schemaId); }
+    catch (error) { return { ok: false, error: 'schema.fetch.failed', state, schemaId, exception: error, notice: `Could not open reading contract schema ${schemaId}.` }; }
+  }
+  if (!entry?.markdown) return { ok: false, error: 'schema.unavailable', state, schemaId, recovery: recovered, notice: `Reading contract schema ${schemaId} is not loaded or bundled for this workspace.` };
+  const semanticQualificationEvidence = entry?.semanticQualification || null;
+  const semanticQualification = qualifySchemaReadingContractMarkdown(entry.markdown, schemaId);
+  if (semanticQualification.state !== 'qualified') return { ok: false, error: 'schema.unavailable', state, schemaId, recovery: recovered, semanticQualification, notice: `Reading contract schema ${schemaId} is unavailable because its material is not qualified as the exact supported Tiinex schema artifact.` };
+  entry = Object.assign({}, entry, { semanticQualification, semanticQualificationEvidence });
+
+  const copied = stateWithWorkspaceStructuralCopy(state, workspace.id);
+  const next = copied.state;
+  const target = copied.workspace;
+  if (!target) return { ok: false, error: 'workspace.missing-after-copy', state, notice: 'No active workspace is available.' };
+  const createdAt = input.clock ? input.clock() : new Date().toISOString();
+  if (entry?.source?.sourceBacked && String(entry.source.adapterId || '').toLowerCase() === 'github') {
+    const coalesced = coalesceRecoveredGithubSchemaSource(target.sources, entry.source, entry.path || recovered?.path || '');
+    if (!coalesced.ok) {
+      return { ok: false, error: coalesced.reason === 'github-source-boundary-ambiguous' ? 'schema.source.ambiguous' : 'schema.source.unavailable', state, schemaId, sourceQualification: coalesced, notice: `Reading contract schema ${schemaId} could not be attached to one truthful exact GitHub source boundary.` };
+    }
+    target.sources = coalesced.sources;
+    entry = Object.assign({}, entry, { source: coalesced.source });
+  }
+  const schemaRecord = makeSchemaRecord({ workspace: target, entry, schemaId, createdAt });
+  const records = Array.isArray(target.records) ? target.records.slice() : [];
+  const materialization = qualifySchemaMaterializationReuse(records, schemaRecord, schemaId);
+  if (materialization.state === 'ambiguous') {
+    return { ok: false, error: 'schema.materialization.ambiguous', state, schemaId, materialization, notice: `Multiple concrete records qualify as the exact reading contract for ${schemaId}; materialization authority is ambiguous.` };
+  }
+  if (materialization.state === 'conflict') {
+    return { ok: false, error: 'schema.materialization.identity-conflict', state, schemaId, materialization, notice: `An unrelated record occupies the reading-contract storage identity for ${schemaId}; it was not overwritten or upgraded.` };
+  }
+  const existingIndex = materialization.index;
+  if (existingIndex >= 0) records[existingIndex] = mergeSchemaNavigationMetadata(records[existingIndex], schemaRecord);
+  else records.unshift(schemaRecord);
+  target.records = records;
+  const selected = existingIndex >= 0 ? records[existingIndex] : schemaRecord;
+  const selectedSource = selected?.source || schemaRecord.source;
+  target.sources = selectedSource?.sourceBacked ? updateRecoveredSchemaSourceCounts(target.sources, selectedSource, target.records) : upsertSchemaSource(target.sources, target.records);
+  target.sourceOrder = Array.isArray(target.sources) ? target.sources.map((source) => source.id).filter(Boolean) : [];
+  next.activeWorkspaceId = target.id;
+  return focusSchemaRecordState({ state: next, workspaceId: target.id, record: selected, schemaId, notice: `Opened reading contract: ${schemaShortLabel(schemaId)}.`, loaded: existingIndex < 0 });
+}
+
+export function findLoadedSchemaRecord(workspace = {}, schemaId = '') {
+  const qualified = qualifyLoadedSchemaRecords(workspace, schemaId);
+  return qualified.state === 'qualified' ? qualified.record : null;
+}
+
+function qualifyLoadedSchemaRecords(workspace = {}, schemaId = '', representationIdentity = '') {
+  const clean = normalizeSchemaId(schemaId);
+  if (!clean) return Object.freeze({ state: 'unavailable', record: null, matches: Object.freeze([]), candidateCount: 0, failures: Object.freeze([]) });
+  const records = Array.isArray(workspace.records) ? workspace.records : [];
+  const candidates = records.filter((record) => loadedSchemaCandidateEvidence(record, clean));
+  const matches = [];
+  const failures = [];
+  for (const record of candidates) {
+    try {
+      if (representationIdentity) {
+        const representation = qualifySchemaRecordRecoveryRepresentation(record);
+        if (representation.state !== 'qualified' || representation.identity !== representationIdentity) {
+          failures.push(Object.freeze({ id: String(record?.id || ''), state: representation.state, reason: representation.reason || 'representation-target-mismatch' }));
+          continue;
+        }
+      }
+      const qualification = qualifySchemaReadingContractMarkdown(record?.markdown || '', clean);
+      if (qualification.state === 'qualified') matches.push(record);
+      else failures.push(Object.freeze({ id: String(record?.id || ''), state: qualification.state }));
+    } catch (exception) {
+      failures.push(Object.freeze({ id: String(record?.id || ''), state: 'unavailable', reason: 'candidate-read-failed', exception }));
+    }
+  }
+  if (matches.length === 1) return Object.freeze({ state: 'qualified', record: matches[0], matches: Object.freeze(matches), candidateCount: candidates.length, failures: Object.freeze(failures) });
+  if (matches.length > 1) return Object.freeze({ state: 'ambiguous', record: null, matches: Object.freeze(matches), candidateCount: candidates.length, failures: Object.freeze(failures) });
+  return Object.freeze({ state: 'unavailable', record: null, matches: Object.freeze([]), candidateCount: candidates.length, failures: Object.freeze(failures) });
+}
+
+function loadedSchemaCandidateEvidence(record = {}, schemaId = '') {
+  const clean = normalizeSchemaId(schemaId);
+  if (!clean || !record || typeof record !== 'object') return '';
+  const navigation = record.schemaNavigation || {};
+  if (normalizeSchemaId(navigation.schemaId) === clean && (navigation.reason === 'reading-contract-badge' || navigation.schema === 'tiinex.workspace.schemaNavigation.v1')) return 'schema-navigation-reading-contract';
+
+  const filename = schemaFilenameForId(clean);
+  const paths = [record.path, record.sourcePath, record.sourceTarget?.sourceArtifactPath]
+    .map((value) => String(value || '').replace(/\\/g, '/').trim())
+    .filter(Boolean);
+  if (filename && paths.some((path) => isSchemaDefinitionPath(path) && path.split('/').filter(Boolean).at(-1) === filename)) return 'schema-definition-path';
+
+  const explicitRole = String(record.materialRole || record.materialKind || record.artifactRole || record.presentationRole || '').trim().toLowerCase();
+  const schemaDefinitionRole = explicitRole === 'schema-definition' || explicitRole === 'schema';
+  const governedId = normalizeSchemaId(record.schemaId || record.currentSchemaId || '');
+  if (schemaDefinitionRole && governedId === clean) return 'schema-definition-role';
+  if (String(record.lifecycleStatus || '').trim().toLowerCase() === 'reading contract' && governedId === clean) return 'reading-contract-lifecycle';
+  return '';
+}
+
+export function schemaPathCandidatesForRecord(record = {}, schemaId = '') {
+  const clean = normalizeSchemaId(schemaId || recordSchemaId(record));
+  const filename = schemaFilenameForId(clean);
+  if (!clean || !filename) return [];
+  const candidates = [];
+  const add = (value) => { const path = normalizePath(value); if (path && !candidates.includes(path)) candidates.push(path); };
+  const parsed = parseArtifactMarkdown(record.markdown || '');
+  const rawCurrent = parsed.envelope?.current?.schema?.raw || '';
+  const linked = markdownLinkHref(rawCurrent);
+  if (linked) add(joinPath(dirname(record.path || ''), linked));
+  add(filename);
+  add(`.topics/.schemas/${filename}`);
+  add(`.schemas/${filename}`);
+  if (record.path) {
+    add(joinPath(dirname(record.path), filename));
+    add(joinPath(dirname(record.path), '../.schemas', filename));
+    const topicsIndex = String(record.path || '').indexOf('.topics/');
+    if (topicsIndex >= 0) add(`${String(record.path).slice(0, topicsIndex)}.topics/.schemas/${filename}`);
+  }
+  const catalogEntry = schemaCatalogEntryForId(clean);
+  if (catalogEntry?.path) add(catalogEntry.path);
+  return candidates;
+}
+
+function makeSchemaRecord({ workspace, entry, schemaId, createdAt }) {
+  const representationIdentity = entry?.source?.sourceBacked ? schemaRecoveryRepresentationIdentity(entry) : '';
+  const path = schemaEntryRecordPath(entry, schemaId);
+  const base = createRecordFromMarkdown(entry.markdown || '', { path, sourceMode: 'app-local-schema', lifecycleStatus: 'reading contract' });
+  return Object.assign({}, base, {
+    id: representationIdentity ? `schema:${workspace.id}:${schemaId}:representation:${encodeURIComponent(representationIdentity)}` : `schema:${workspace.id}:${schemaId}`,
+    path,
+    sourceMode: entry.source?.sourceBacked ? 'source-backed' : 'app-local-schema',
+    lifecycleStatus: base.lifecycleStatus || 'reading contract',
+    status: base.status || 'schema ok',
+    source: entry.source?.sourceBacked ? Object.assign({}, entry.source) : schemaSourceBase(recordsForSource(workspace.records).length + 1),
+    sourceTarget: entry.source?.sourceBacked ? {
+      sourceArtifactPath: path,
+      declaredLocator: entry.declaredHref || entry.declaredLocator || '',
+      effectiveRequestTarget: entry.effectiveRequestTarget || entry.fetchUrl || '',
+      finalRetrievedTarget: entry.finalRetrievedTarget || entry.effectiveRequestTarget || entry.fetchUrl || '',
+      inputTarget: entry.finalRetrievedTarget || entry.effectiveRequestTarget || entry.fetchUrl || entry.browseUrl || path,
+      browseUrl: entry.browseUrl || entry.source?.permalink || entry.finalRetrievedTarget || entry.fetchUrl || '',
+      rawUrl: entry.finalRetrievedTarget || entry.fetchUrl || ''
+    } : base.sourceTarget,
+    schemaNavigation: {
+      schema: 'tiinex.workspace.schemaNavigation.v1',
+      schemaId,
+      loadedAt: createdAt,
+      reason: 'reading-contract-badge',
+      source: entry.source?.sourceBacked ? 'declared-reading-contract-target' : 'bundled-viewer-schema-registry',
+      representationIdentity,
+      declaredLocator: entry.declaredHref || entry.declaredLocator || '',
+      effectiveRequestTarget: entry.effectiveRequestTarget || entry.fetchUrl || '',
+      finalRetrievedTarget: entry.finalRetrievedTarget || entry.effectiveRequestTarget || entry.fetchUrl || '',
+      semanticQualification: entry.semanticQualification || qualifySchemaReadingContractMarkdown(entry.markdown || '', schemaId),
+      candidates: schemaPathCandidatesForRecord(base, schemaId)
+    }
+  });
+}
+
+function mergeSchemaNavigationMetadata(existing = {}, schemaRecord = {}) {
+  return Object.assign({}, existing, {
+    schemaNavigation: Object.assign({}, existing.schemaNavigation || {}, schemaRecord.schemaNavigation || {}),
+    source: existing.source || schemaRecord.source,
+    sourceMode: existing.sourceMode || schemaRecord.sourceMode
+  });
+}
+
+function updateRecoveredSchemaSourceCounts(sources = [], source = {}, records = []) {
+  const list = Array.isArray(sources) ? sources.slice() : [];
+  const index = list.findIndex((item) => String(item?.id || '') === String(source.id || ''));
+  if (index < 0) return list.concat(source);
+  const current = list[index];
+  const sourceRecords = (Array.isArray(records) ? records : []).filter((record) => String(record?.source?.id || '') === String(source.id || ''));
+  const recoveredSchemaRecords = sourceRecords.filter((record) => record?.schemaNavigation?.reason === 'reading-contract-badge');
+  const explicitFileRefs = normalizeExplicitFileRefs(current.explicitFileRefs || current.config?.explicitFileRefs || []);
+  const explicitFiles = Object.assign({}, current.surfaces?.explicitFiles || {}, { requested: true, loaded: recoveredSchemaRecords.length, requestedCount: explicitFileRefs.length });
+  list[index] = Object.assign({}, current, {
+    count: Math.max(Number(current.count || 0), sourceRecords.length),
+    recordCount: Math.max(Number(current.recordCount || 0), sourceRecords.length),
+    explicitFileRefs,
+    config: Object.assign({}, current.config || {}, { explicitFileRefs: explicitFileRefs.slice() }),
+    surfaces: Object.assign({}, current.surfaces || {}, { explicitFiles })
+  });
+  return list;
+}
+
+function upsertSchemaSource(sources = [], records = []) {
+  const list = Array.isArray(sources) ? sources.slice() : [];
+  const count = recordsForSource(records).length;
+  const source = schemaSourceBase(count);
+  const index = list.findIndex((item) => item.id === SCHEMA_SOURCE_ID);
+  if (index >= 0) list[index] = Object.assign({}, list[index], source);
+  else list.push(source);
+  return list;
+}
+
+function schemaSourceBase(count = 0) {
+  return {
+    id: SCHEMA_SOURCE_ID,
+    label: SCHEMA_SOURCE_LABEL,
+    kind: 'app-local',
+    adapterId: 'schema-registry',
+    sourceKind: 'app-local.schema',
+    sourceBacked: false,
+    discoveryState: 'loaded',
+    count: Number(count || 0),
+    recordCount: Number(count || 0),
+    boundary: SCHEMA_SOURCE_BOUNDARY,
+    surfaces: { schemas: { requested: true, state: 'loaded', loaded: Number(count || 0) } }
+  };
+}
+
+function recordsForSource(records = []) { return (Array.isArray(records) ? records : []).filter((record) => record?.source?.id === SCHEMA_SOURCE_ID); }
+function workspaceById(state = {}, workspaceId = '') { return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => String(workspace?.id || '') === String(workspaceId || '')) || null; }
+function recordById(workspace = {}, recordId = '') { return (Array.isArray(workspace.records) ? workspace.records : []).find((record) => String(record?.id || '') === String(recordId || '')) || null; }
+function recordSchemaId(record = {}) { return record?.schemaId || record?.currentSchemaId || ''; }
+function normalizeSchemaId(value = '') { return String(value || '').replace(/^Current Schema:\s*/i, '').replace(/^\[([^\]]+)\]\([^)]*\)$/u, '$1').trim(); }
+function isSchemaMarkdownPath(path = '') { return /\.schema\.md$/i.test(String(path || '').trim()); }
+function schemaShortLabel(schemaId = '') { return normalizeSchemaId(schemaId).replace(/^tiinex\./, '').replace(/\.v\d+$/, '') || 'schema'; }
+function markdownLinkHref(value = '') { return String(value || '').match(/^\[[^\]]+\]\(([^)]+)\)$/)?.[1] || ''; }
+function normalizePath(value = '') {
+  const raw = String(value || '').replace(/\\/g, '/').trim();
+  if (!raw) return '';
+  const out = [];
+  for (const part of raw.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}
+function schemaEntryRecordPath(entry = {}, schemaId = '') {
+  const raw = String(entry.path || '').trim();
+  if (/^https?:\/\//u.test(raw)) return raw;
+  return normalizePath(raw || schemaFilenameForId(schemaId));
+}
+function dirname(path = '') { const parts = normalizePath(path).split('/').filter(Boolean); parts.pop(); return parts.join('/'); }
+function joinPath(...parts) { return normalizePath(parts.filter(Boolean).join('/')); }

package/src/app/schemaNavigationMaterialization.js

@@ -0,0 +1,171 @@
+import { normalizeExplicitFileRefs } from '@tiinex/core/sources/source.explicitTargets.js';
+import { qualifySchemaRecordRecoveryRepresentation } from './schemaSourceRecovery.js';
+import { qualifySchemaReadingContractMarkdown } from './schemaReadingContractQualification.js';
+
+export function qualifySchemaMaterializationReuse(records = [], schemaRecord = {}, schemaId = '') {
+  const collisions = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    const evidence = materializationCollisionEvidence(record, schemaRecord);
+    if (!evidence.dimensions.length) continue;
+    let semanticQualification = null;
+    let representationQualification = null;
+    let reusable = false;
+    let readFailure = null;
+    try {
+      const requiredRepresentation = String(schemaRecord?.schemaNavigation?.representationIdentity || '');
+      if (requiredRepresentation) {
+        representationQualification = qualifySchemaRecordRecoveryRepresentation(record);
+        if (representationQualification.state !== 'qualified' || representationQualification.identity !== requiredRepresentation) {
+          collisions.push(Object.freeze({ index, id: String(record?.id || ''), dimensions: Object.freeze(evidence.dimensions), reusable: false, representationQualification, semanticQualification: null, readFailure: null }));
+          continue;
+        }
+      }
+      semanticQualification = qualifySchemaReadingContractMarkdown(record?.markdown || '', schemaId);
+      reusable = semanticQualification.state === 'qualified';
+    } catch (exception) {
+      readFailure = exception;
+    }
+    collisions.push(Object.freeze({ index, id: String(record?.id || ''), dimensions: Object.freeze(evidence.dimensions), reusable, representationQualification, semanticQualification, readFailure }));
+  }
+
+  const reusable = collisions.filter((candidate) => candidate.reusable);
+  if (reusable.length === 1) return Object.freeze({ state: 'qualified', index: reusable[0].index, collisions: Object.freeze(collisions), reusable: Object.freeze(reusable) });
+  if (reusable.length > 1) return Object.freeze({ state: 'ambiguous', index: -1, collisions: Object.freeze(collisions), reusable: Object.freeze(reusable) });
+  const representationBackedIdentity = Boolean(schemaRecord?.schemaNavigation?.representationIdentity);
+  const storageConflicts = collisions.filter((candidate) => candidate.dimensions.includes('id') || (!representationBackedIdentity && candidate.dimensions.includes('path')));
+  if (storageConflicts.length) return Object.freeze({ state: 'conflict', index: -1, collisions: Object.freeze(collisions), reusable: Object.freeze([]), storageConflicts: Object.freeze(storageConflicts) });
+  return Object.freeze({ state: 'materialize', index: -1, collisions: Object.freeze(collisions), reusable: Object.freeze([]) });
+}
+
+export function coalesceRecoveredGithubSchemaSource(sources = [], recovered = {}, targetPath = '') {
+  const list = Array.isArray(sources) ? sources.slice() : [];
+  const targetBoundary = exactGithubSchemaBoundary(recovered, targetPath);
+  if (targetBoundary.state !== 'qualified') return { ok: false, reason: 'github-recovered-source-boundary-unavailable', qualification: targetBoundary, source: null, sources: list };
+  const { repo, ref, rootPath, path } = targetBoundary;
+  const compatible = [];
+  for (let index = 0; index < list.length; index += 1) {
+    const qualification = compatibleGithubSchemaBoundary(list[index], { repo, ref, rootPath });
+    if (qualification.state === 'qualified') compatible.push(index);
+  }
+  if (compatible.length > 1) return { ok: false, reason: 'github-source-boundary-ambiguous', matchingIndices: compatible.slice(), source: null, sources: list };
+  const compatibleIndex = compatible.length === 1 ? compatible[0] : -1;
+  const existing = compatibleIndex >= 0 ? list[compatibleIndex] : null;
+  const explicitFileRefs = normalizeExplicitFileRefs([...(existing?.explicitFileRefs || existing?.config?.explicitFileRefs || []), path]);
+  const id = existing?.id || `github-exact:${repo.toLowerCase()}:${ref || 'default'}:${rootPath}`;
+  const source = Object.assign({}, existing || {}, recovered, {
+    id,
+    label: existing?.label || recovered.label || repo,
+    kind: existing?.kind || 'github-tree',
+    adapterId: 'github',
+    sourceKind: 'github.repo',
+    repo,
+    repository: repo,
+    ref,
+    rootPath,
+    sourceBacked: true,
+    originReferenceSource: false,
+    recoveryOnly: false,
+    loadable: true,
+    closeable: existing?.closeable !== false,
+    repoDiscovery: Boolean(existing?.repoDiscovery),
+    issueDiscovery: Boolean(existing?.issueDiscovery),
+    issueUrls: existing?.issueUrls || existing?.config?.issueUrls || '',
+    explicitFileRefs,
+    config: Object.assign({}, existing?.config || {}, recovered.config || {}, { repo, ref, rootPath, issueUrls: existing?.issueUrls || existing?.config?.issueUrls || '', explicitFileRefs: explicitFileRefs.slice() }),
+    requestedSurfaces: Object.assign({}, existing?.requestedSurfaces || {}, {
+      explicitFiles: Object.assign({}, existing?.requestedSurfaces?.explicitFiles || {}, { requested: true, requestedCount: explicitFileRefs.length })
+    }),
+    boundary: existing?.boundary || 'configured exact-target GitHub source; broad discovery remains explicit'
+  });
+  delete source.path;
+  delete source.permalink;
+  if (compatibleIndex >= 0) list[compatibleIndex] = source;
+  else {
+    if (list.some((item) => String(item?.id || '') === String(source.id || ''))) return { ok: false, reason: 'github-source-id-conflict', source: null, sources: list };
+    list.push(source);
+  }
+  return { ok: true, source, sources: list };
+}
+
+function materializationCollisionEvidence(record = {}, schemaRecord = {}) {
+  const dimensions = [];
+  if (String(record?.id || '') && String(record.id) === String(schemaRecord?.id || '')) dimensions.push('id');
+  const leftPath = normalizePath(record?.path || '');
+  const rightPath = normalizePath(schemaRecord?.path || '');
+  if (leftPath && rightPath && leftPath === rightPath) dimensions.push('path');
+  try {
+    const leftRepresentation = qualifySchemaRecordRecoveryRepresentation(record);
+    const rightRepresentation = qualifySchemaRecordRecoveryRepresentation(schemaRecord);
+    const leftSchemaId = normalizeSchemaId(recordSchemaId(record) || record?.schemaNavigation?.schemaId);
+    const rightSchemaId = normalizeSchemaId(recordSchemaId(schemaRecord) || schemaRecord?.schemaNavigation?.schemaId);
+    if (leftRepresentation.state === 'qualified' && rightRepresentation.state === 'qualified' && leftRepresentation.identity === rightRepresentation.identity && leftSchemaId === rightSchemaId) dimensions.push('representation');
+  } catch {
+    // Collision discovery is bounded evidence only; semantic reuse qualification owns material read failures.
+  }
+  return Object.freeze({ dimensions });
+}
+
+function compatibleGithubSchemaBoundary(source = {}, target = {}) {
+  if (String(source.adapterId || '').toLowerCase() !== 'github') return Object.freeze({ state: 'unavailable', reason: 'not-github-source' });
+  if (source.originReferenceSource === true || source.recoveryOnly === true) return Object.freeze({ state: 'unavailable', reason: 'non-coalescing-source-boundary' });
+  const repo = qualifyExactSourceDimension([source.repo, source.repository, source.config?.repo]);
+  const ref = qualifyExactSourceDimension([source.ref, source.config?.ref]);
+  const root = qualifyExactSourceDimension([source.rootPath, source.config?.rootPath]);
+  if (repo.state !== 'qualified') return Object.freeze({ state: repo.state, reason: `github-source-repo-${repo.state}`, repo, ref, root });
+  if (ref.state !== 'qualified') return Object.freeze({ state: ref.state, reason: `github-source-ref-${ref.state}`, repo, ref, root });
+  if (root.state === 'ambiguous') return Object.freeze({ state: 'ambiguous', reason: 'github-source-root-ambiguous', repo, ref, root });
+  const rootPath = root.state === 'qualified' ? schemaSourceRootPath('', root.value) : '.';
+  const matches = repo.value === String(target.repo || '') && ref.value === String(target.ref || '') && rootPath === String(target.rootPath || '');
+  return Object.freeze({ state: matches ? 'qualified' : 'unavailable', reason: matches ? '' : 'github-source-boundary-mismatch', repo, ref, root, rootPath });
+}
+
+function exactGithubSchemaBoundary(source = {}, targetPath = '') {
+  if (String(source.adapterId || '').toLowerCase() !== 'github') return Object.freeze({ state: 'unavailable', reason: 'not-github-source' });
+  const repo = qualifyExactSourceDimension([source.repo, source.repository, source.config?.repo]);
+  const ref = qualifyExactSourceDimension([source.ref, source.config?.ref]);
+  const configuredRoot = qualifyExactSourceDimension([source.rootPath, source.config?.rootPath]);
+  if (repo.state !== 'qualified') return Object.freeze({ state: repo.state, reason: `github-recovered-repo-${repo.state}`, repo, ref, configuredRoot });
+  if (ref.state !== 'qualified') return Object.freeze({ state: ref.state, reason: `github-recovered-ref-${ref.state}`, repo, ref, configuredRoot });
+  if (configuredRoot.state === 'ambiguous') return Object.freeze({ state: 'ambiguous', reason: 'github-recovered-root-ambiguous', repo, ref, configuredRoot });
+  const path = normalizePath(targetPath || source.path || '');
+  if (!path) return Object.freeze({ state: 'unavailable', reason: 'github-recovered-path-unavailable', repo, ref, configuredRoot });
+  const rootPath = schemaSourceRootPath(path, configuredRoot.state === 'qualified' ? configuredRoot.value : '');
+  return Object.freeze({ state: 'qualified', repo: repo.value, ref: ref.value, rootPath, path, repoQualification: repo, refQualification: ref, rootQualification: configuredRoot });
+}
+
+function qualifyExactSourceDimension(values = []) {
+  const asserted = [];
+  for (const value of values) {
+    if (value === undefined || value === null) continue;
+    const raw = String(value);
+    if (!raw || asserted.includes(raw)) continue;
+    asserted.push(raw);
+  }
+  if (asserted.length === 1) return Object.freeze({ state: 'qualified', value: asserted[0], values: Object.freeze(asserted) });
+  if (asserted.length > 1) return Object.freeze({ state: 'ambiguous', value: '', values: Object.freeze(asserted) });
+  return Object.freeze({ state: 'unavailable', value: '', values: Object.freeze([]) });
+}
+
+function schemaSourceRootPath(path = '', configuredRoot = '') {
+  const root = normalizePath(configuredRoot);
+  if (root && root !== '.') return root;
+  const clean = normalizePath(path);
+  if (clean === '.topics' || clean.startsWith('.topics/')) return '.topics';
+  const parts = clean.split('/').filter(Boolean);
+  return parts.length > 1 ? parts[0] : '.';
+}
+
+function recordSchemaId(record = {}) { return record?.schemaId || record?.currentSchemaId || ''; }
+function normalizeSchemaId(value = '') { return String(value || '').replace(/^Current Schema:\s*/i, '').replace(/^\[([^\]]+)\]\([^)]*\)$/u, '$1').trim(); }
+function normalizePath(value = '') {
+  const raw = String(value || '').replace(/\\/g, '/').trim();
+  if (!raw) return '';
+  const out = [];
+  for (const part of raw.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}

package/src/app/schemaNavigationRuntimeCatalog.js

@@ -0,0 +1,25 @@
+import { resolveSchemaModule } from '@tiinex/core/schemas/resolver.js';
+import { schemaCatalogEntryForId } from '../schemas/schemaMarkdownCatalog.js';
+import { qualifyBundledSchemaReadableText, qualifyBundledSchemaSource } from '@tiinex/core/schemas/schema.source.js';
+
+export async function loadViewerSchemaMarkdown(schemaId = '', fetchImpl = globalThis.fetch) {
+  const id = String(schemaId || '').trim();
+  const entry = schemaCatalogEntryForId(id);
+  const resolution = resolveSchemaModule({ schemaId: id });
+  const source = resolution?.fallbackUsed ? null : resolution?.module?.schemaSource;
+  if (!entry || source?.readable !== true) return null;
+  const qualification = qualifyBundledSchemaSource(source);
+  if (qualification.state !== 'qualified') return null;
+  if (!source.assetUrl || typeof fetchImpl !== 'function') return null;
+  const response = await fetchImpl(source.assetUrl);
+  if (!response?.ok) throw new Error(`schema.fetch.failed:${response?.status || 'unknown'}`);
+  const markdown = await response.text();
+  const readableQualification = qualifyBundledSchemaReadableText(source, markdown);
+  if (readableQualification.state !== 'qualified') return null;
+  return Object.assign({}, entry, {
+    markdown,
+    assetUrl: source.assetUrl,
+    sourceQualification: qualification,
+    readableQualification
+  });
+}

package/src/app/schemaNavigationState.js

@@ -0,0 +1,66 @@
+import { stateWithActiveWorkspace, stateWithWorkspaceViewPatch } from './workspaceMulticolumn.js';
+import { qualifySchemaRecordRecoveryRepresentation } from './schemaSourceRecovery.js';
+
+export function stateWithWorkspaceStructuralCopy(state = {}, workspaceId = '') {
+  const workspaces = Array.isArray(state.workspaces) ? state.workspaces : [];
+  const index = workspaces.findIndex((workspace) => String(workspace?.id || '') === String(workspaceId || ''));
+  if (index < 0) return { state, workspace: null };
+  const current = workspaces[index];
+  const workspace = Object.assign({}, current, {
+    records: Array.isArray(current.records) ? current.records.slice() : [],
+    sources: Array.isArray(current.sources) ? current.sources.slice() : [],
+    sourceOrder: Array.isArray(current.sourceOrder) ? current.sourceOrder.slice() : []
+  });
+  const nextWorkspaces = workspaces.slice();
+  nextWorkspaces[index] = workspace;
+  return { state: Object.assign({}, state, { workspaces: nextWorkspaces }), workspace };
+}
+
+export function stateWithReplacedWorkspaceRecord(state = {}, workspaceId = '', existing = null, replacement = null) {
+  const copied = stateWithWorkspaceStructuralCopy(state, workspaceId);
+  if (!copied.workspace || !replacement) return state;
+  const records = copied.workspace.records;
+  const index = records.findIndex((record) => record === existing || (existing?.id && String(record?.id || '') === String(existing.id)));
+  if (index < 0) return state;
+  records[index] = replacement;
+  return copied.state;
+}
+
+export function recordWithTruthfulRepresentationMetadata(record = {}) {
+  const navigation = record?.schemaNavigation;
+  if (!navigation || typeof navigation !== 'object') return record;
+  const representation = qualifySchemaRecordRecoveryRepresentation(record);
+  const truthfulIdentity = representation.state === 'qualified' ? representation.identity : '';
+  if (String(navigation.representationIdentity || '') === truthfulIdentity) return record;
+  return Object.assign({}, record, {
+    schemaNavigation: Object.assign({}, navigation, {
+      representationIdentity: truthfulIdentity,
+      representationQualification: Object.freeze({ state: representation.state, reason: representation.reason || '' })
+    })
+  });
+}
+
+
+export function focusSchemaRecordState({ state, workspaceId, record, schemaId, notice, existing = false, loaded = false }) {
+  const id = String(workspaceId || state?.activeWorkspaceId || '').trim();
+  const truthfulRecord = recordWithTruthfulRepresentationMetadata(record);
+  let next = truthfulRecord === record ? state : stateWithReplacedWorkspaceRecord(state, id, record, truthfulRecord);
+  next = stateWithActiveWorkspace(next, id);
+  const currentView = next.workspaceViews?.[id] || next.view || {};
+  next = stateWithWorkspaceViewPatch(next, id, {
+    workspaceVerse: 'lineage',
+    selectedRecordId: truthfulRecord.id,
+    lineageQuery: '',
+    lineageAuditReport: null,
+    lineageLoadReport: null,
+    expandedLineageRecordIds: unique([truthfulRecord.id].concat(currentView.expandedLineageRecordIds || []))
+  });
+  return { ok: true, state: next, workspace: workspaceById(next, id), record: truthfulRecord, schemaId, existing, loaded, commitMode: 'push', notice };
+}
+
+function workspaceById(state = {}, workspaceId = '') {
+  return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => String(workspace?.id || '') === String(workspaceId || '')) || null;
+}
+function unique(values = []) {
+  return Array.from(new Set(values.map((value) => String(value || '').trim()).filter(Boolean)));
+}

package/src/app/schemaReadingContractQualification.js

@@ -0,0 +1,91 @@
+import { parseArtifactMarkdown } from '@tiinex/core/artifacts/artifact.parse.js';
+import { sha256Hex, utf8Bytes } from '@tiinex/core/export/package.bytes.js';
+import { resolveSchemaModule } from '@tiinex/core/schemas/resolver.js';
+import { validateArtifact } from '@tiinex/core/validation/validateArtifact.js';
+
+export const SCHEMA_READING_CONTRACT_QUALIFICATION_SCHEMA_ID = 'tiinex.site.schema-reading-contract-qualification.v1';
+
+export function qualifySchemaReadingContractMarkdown(markdown = '', requestedSchemaId = '') {
+  const text = String(markdown ?? '');
+  const requested = String(requestedSchemaId || '').trim();
+  const findings = [];
+  let parsed = null;
+  let parseException = null;
+  try { parsed = parseArtifactMarkdown(text); }
+  catch (error) { parseException = error; }
+
+  const observedSchemaId = String(parsed?.envelope?.current?.schema?.id || '').trim();
+  const resolution = requested ? resolveSchemaModule({ schemaId: requested }) : null;
+  const module = resolution?.module || null;
+  const exactModule = Boolean(requested && !resolution?.fallbackUsed && String(module?.id || '') === requested);
+  const expectedChecksum = exactModule ? String(module?.binding?.checksum?.value || module?.binding?.checksum || '').trim() : '';
+  const checksum = text ? sha256Hex(utf8Bytes(text)) : '';
+  const checksumExact = Boolean(expectedChecksum && checksum === expectedChecksum);
+  const identityExact = Boolean(requested && observedSchemaId === requested);
+
+  let artifactValidation = null;
+  if (exactModule && identityExact && checksumExact && !parseException) {
+    artifactValidation = validateArtifact({ markdown: text, parsed, resolution, schemaReferenceAuthorities: sourceQualifiedSchemaReferenceContext(parsed) });
+  }
+  const validationState = String(artifactValidation?.validation?.state || '');
+  const validationExact = requested === 'tiinex.root.v1'
+    ? validationState === 'root-validated'
+    : validationState === 'exact-schema-validated';
+  const validationErrors = Array.isArray(artifactValidation?.findings)
+    ? artifactValidation.findings.filter((finding) => String(finding?.severity || '').toLowerCase() === 'error' && !['machine-contract', 'integrity'].includes(String(finding?.qualification || '')))
+    : [];
+
+  if (!requested) findings.push('Requested schema identifier authority is unavailable.');
+  if (!text.trim()) findings.push('Schema reading-contract material is empty.');
+  if (parseException) findings.push(`Schema reading-contract material could not be parsed as a Tiinex artifact: ${String(parseException?.message || parseException)}.`);
+  if (!identityExact) findings.push(`Schema reading-contract Current Schema must be exactly ${requested || '(unavailable)'}; observed ${observedSchemaId || '(empty)'}.`);
+  if (!exactModule) findings.push(`No exact installed schema module authority is available for ${requested || '(unavailable)'}.`);
+  if (exactModule && !expectedChecksum) findings.push(`Exact schema source checksum authority is unavailable for ${requested}.`);
+  if (exactModule && expectedChecksum && !checksumExact) findings.push(`Schema reading-contract bytes do not match the exact installed source checksum for ${requested}.`);
+  if (exactModule && identityExact && checksumExact && !validationExact) findings.push(`Schema reading-contract material did not reach exact supported artifact validation for ${requested}.`);
+  if (validationErrors.length) findings.push(`Schema reading-contract material has ${validationErrors.length} error finding(s) under exact supported artifact validation.`);
+
+  const qualified = Boolean(
+    requested
+    && text.trim()
+    && !parseException
+    && identityExact
+    && exactModule
+    && expectedChecksum
+    && checksumExact
+    && validationExact
+    && validationErrors.length === 0
+  );
+
+  return Object.freeze({
+    schema: SCHEMA_READING_CONTRACT_QUALIFICATION_SCHEMA_ID,
+    state: qualified ? 'qualified' : 'unavailable',
+    requestedSchemaId: requested,
+    observedSchemaId,
+    checksum,
+    expectedChecksum,
+    identityState: identityExact ? 'qualified' : 'unavailable',
+    sourceChecksumState: checksumExact ? 'qualified' : 'unavailable',
+    validationState: validationExact ? 'qualified' : 'unavailable',
+    validationCoverage: String(artifactValidation?.validation?.coverage || ''),
+    moduleAuthorityState: exactModule ? 'qualified' : 'unavailable',
+    findings: Object.freeze(findings)
+  });
+}
+
+
+function sourceQualifiedSchemaReferenceContext(parsed = {}) {
+  const parent = parsed?.envelope?.parent || {};
+  return Object.freeze({
+    envelope: declaredReferenceAuthority(parsed?.envelope?.envelopeSchema),
+    current: declaredReferenceAuthority(parsed?.envelope?.current?.schema),
+    parent: declaredReferenceAuthority(parent?.schema)
+  });
+}
+
+function declaredReferenceAuthority(reference = {}) {
+  const schemaId = String(reference?.id || '').trim();
+  const target = String(reference?.target || '').trim();
+  if (!schemaId) return null;
+  return Object.freeze({ schemaId, exactTargets: Object.freeze(target ? [target] : []), preferredTarget: target, resolutionState: 'qualified', evidence: Object.freeze({ source: 'exact-installed-schema-source-checksum' }) });
+}