@tiinex/core 0.1.1

package/src/schemas/schema/module/tiinex.schema.module.v1.schema.source.js

@@ -0,0 +1,9 @@
+import binding from './tiinex.schema.module.v1.schema.json' with { type: 'json' };
+import projection from './tiinex.schema.module.v1.schema.runtime.json' with { type: 'json' };
+import { defineBundledSchemaSource } from '../../schema.source.js';
+
+export const schemaSource = defineBundledSchemaSource(binding, projection, Object.freeze({
+  bundledPath: 'src/schemas/schema/module/tiinex.schema.module.v1.schema.md',
+  sourceLabel: 'Viewer schema registry',
+  assetUrl: new URL('./tiinex.schema.module.v1.schema.md', import.meta.url).href
+}));

package/src/schemas/schema/module/tiinex.schema.module.v1.sv.i18n.json

@@ -0,0 +1,4 @@
+{
+  "label": "Schema Module",
+  "summary": "Capability bundle around schema interpretation, viewing, validation, forms, and fallback behavior."
+}

package/src/schemas/schema/module/tiinex.schema.module.v1.transitions.js

@@ -0,0 +1 @@
+export const moduleTransitions = Object.freeze([{ id: 'inspect', label: 'Inspect', sideEffect: 'none' }]);

package/src/schemas/schema/module/tiinex.schema.module.v1.validate.js

@@ -0,0 +1 @@
+export function moduleValidate(artifact) { return [{ severity: 'info', code: 'tiinex.schema.module.v1.validation.scaffold', message: 'Initial schema validation scaffold; authoritative contract parsing comes next.' }]; }

package/src/schemas/schema.factory.descriptor.js

@@ -0,0 +1,104 @@
+export const SCHEMA_FACTORY_DESCRIPTOR_SCHEMA_ID = 'tiinex.schema.factory.descriptor.v1';
+
+export function buildSchemaFactoryDescriptor(module = {}, capabilities = {}) {
+  const sourceQualification = typeof module?.schemaSource?.qualify === 'function' ? module.schemaSource.qualify() : null;
+  const compiled = sourceQualification?.state === 'qualified' ? sourceQualification.compiledContract : null;
+  const validation = compiled?.validationContract || null;
+  const creation = compiled?.creation || null;
+  const ordinaryGroups = validation?.validation?.ordinaryGroups || [];
+  const constraints = validation?.constraints || [];
+  const sections = ordinaryGroups.map((group) => Object.freeze({
+    group: String(group?.group || ''),
+    heading: String(group?.target?.heading || ''),
+    title: String(group?.target?.title || group?.group || ''),
+    requiredness: String(group?.target?.requiredness || ''),
+    qualification: String(group?.qualification || group?.target?.qualification || 'unresolved'),
+    requiredFields: Object.freeze([...(group?.requiredFields || [])]),
+    optionalFields: Object.freeze([...(group?.optionalFields || [])]),
+    contributors: Object.freeze((group?.contributors || []).map((item) => deepFreezeJson(item))),
+    fieldConstraints: Object.freeze(constraints.filter((item) => String(item?.targetGroup || item?.sourceGroup || '') === String(group?.group || '')).map((item) => deepFreezeJson(item)))
+  }));
+  const declarations = (validation?.declarations || []).map((contract) => Object.freeze({
+    group: String(contract?.group || ''),
+    targetHeadings: Object.freeze([...(contract?.targetHeadings || [])]),
+    entryShape: Object.freeze([...(contract?.entryShape || [])]),
+    requiredFields: Object.freeze([...(contract?.requiredFields || [])]),
+    optionalFields: Object.freeze([...(contract?.optionalFields || [])]),
+    allowLiteralNone: Boolean(contract?.allowLiteralNone),
+    fieldConstraints: Object.freeze(constraints.filter((item) => String(item?.targetGroup || item?.sourceGroup || '') === String(contract?.group || '')).map((item) => deepFreezeJson(item)))
+  }));
+  const requiredShape = creation?.requiredShape || [];
+  return Object.freeze({
+    schema: SCHEMA_FACTORY_DESCRIPTOR_SCHEMA_ID,
+    schemaId: String(module?.id || compiled?.schemaId || ''),
+    label: String(module?.label || module?.id || ''),
+    kind: String(module?.kind || ''),
+    role: String(module?.role || ''),
+    source: Object.freeze({
+      state: String(sourceQualification?.state || 'unavailable'),
+      checksum: String(sourceQualification?.checksum || ''),
+      path: String(sourceQualification?.authority?.path || ''),
+      repository: String(sourceQualification?.authority?.repository || ''),
+      commit: String(sourceQualification?.authority?.commit || '')
+    }),
+    inheritance: Object.freeze({
+      parentSchemaId: String(module?.parentSchemaId || ''),
+      lineage: Object.freeze([...(validation?.lineage || [])]),
+      qualification: deepFreezeJson(validation?.lineageQualification || { state: 'unavailable', complete: false, findings: ['Compiled validation lineage unavailable.'] }),
+      resolution: deepFreezeJson(validation?.inheritanceResolution || { schema: 'tiinex.portable.schema-inheritance-resolution.v1', state: 'not-declared', applications: [], findings: [] })
+    }),
+    sections: Object.freeze(sections),
+    declarations: Object.freeze(declarations),
+    fieldShapes: Object.freeze((validation?.validation?.fieldShapes || []).map((item) => deepFreezeJson(item))),
+    machineShapes: deepFreezeJson(validation?.machineShapes || { schema: '', definitions: [], active: [], findings: [] }),
+    creation: Object.freeze({
+      authorityState: String(capabilities?.generation?.authority?.state || (creation ? 'qualified' : 'unavailable')),
+      requiredInputs: Object.freeze([...(creation?.requiredInputs || [])]),
+      optionalInputs: Object.freeze([...(creation?.optionalInputs || [])]),
+      inputBindings: Object.freeze((creation?.inputBindings || []).map((item) => deepFreezeJson(item))),
+      supplementalRequiredFields: Object.freeze((creation?.supplementalRequiredFields || []).map((item) => deepFreezeJson(item))),
+      representationSections: Object.freeze([...(creation?.representationSections || [])]),
+      requiredShape: Object.freeze(requiredShape.map((item) => deepFreezeJson(item))),
+      residualRequiredShape: Object.freeze(requiredShape.filter((item) => String(item?.primitive?.kind || 'residual') === 'residual').map((item) => deepFreezeJson(item)))
+    }),
+    generation: Object.freeze({
+      authorityState: String(capabilities?.generation?.authority?.state || (creation ? 'qualified' : 'unavailable')),
+      implementationState: String(capabilities?.generation?.implementation?.state || 'unavailable'),
+      ready: Boolean(capabilities?.generation?.ready),
+      boundary: 'Artifact Creation Contract + generic renderer qualification only; this does not authorize an invocable lifecycle transition.'
+    }),
+    invocation: Object.freeze({
+      create: Object.freeze({
+        state: capabilities?.actions?.create?.status === 'implemented' ? 'qualified' : 'unavailable',
+        authority: 'canonical-transition-definition',
+        applicability: capabilities?.actions?.create?.status === 'implemented' ? 'explicitly-qualified' : 'not-qualified',
+        boundary: 'Invocable Create is independent from generation authority and must not be inferred from Artifact Creation Contract presence.'
+      })
+    }),
+    capabilities: deepFreezeJson(capabilities),
+    transitionParticipation: Object.freeze({
+      authority: 'canonical-transition-definition',
+      companionMetadataPresent: Boolean(module?.transitions && (typeof module.transitions === 'function' || Object.keys(module.transitions || {}).length)),
+      applicability: 'not-inferred-from-schema-module'
+    }),
+    relationAndCompanionNeeds: Object.freeze({
+      relationMetadataPresent: Boolean(module?.relations),
+      findingsCompanionPresent: Boolean(module?.findings),
+      i18nCompanionPresent: Boolean(module?.i18n),
+      presenterPresent: typeof module?.present === 'function',
+      policy: 'presence-only-no-semantic-inference'
+    }),
+    findings: Object.freeze([
+      ...(sourceQualification?.findings || []).map((item) => typeof item === 'string' ? item : String(item?.message || item?.code || item)),
+      ...(validation?.lineageQualification?.findings || []).map(String)
+    ])
+  });
+}
+
+function deepFreezeJson(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return Object.freeze(value.map(deepFreezeJson));
+  const out = {};
+  for (const [key, item] of Object.entries(value)) out[key] = deepFreezeJson(item);
+  return Object.freeze(out);
+}

package/src/schemas/schema.githubSourceTarget.js

@@ -0,0 +1,131 @@
+export const EXACT_GITHUB_SCHEMA_SOURCE_TARGET_SCHEMA_ID = 'tiinex.site.exact-github-schema-source-target.v1';
+export const GITHUB_SCHEMA_SOURCE_PROVIDER_QUALIFICATION_SCHEMA_ID = 'tiinex.site.github-schema-source-provider-qualification.v1';
+
+export function canonicalGithubSchemaSourceTargets(sourceAuthority = null) {
+  const sourceInputFindings = exactGithubSchemaSourceInputFindings(sourceAuthority);
+  const qualified = exactGithubSchemaSourceIdentity(sourceAuthority);
+  if (!qualified) return Object.freeze({
+    schema: EXACT_GITHUB_SCHEMA_SOURCE_TARGET_SCHEMA_ID,
+    state: 'unavailable',
+    repository: '',
+    commit: '',
+    path: '',
+    blobUrl: '',
+    rawUrl: '',
+    targets: Object.freeze([]),
+    findings: Object.freeze(sourceInputFindings.length ? sourceInputFindings : ['Exact GitHub schema-source repository, commit, and path authority is unavailable.'])
+  });
+  const { blobUrl, rawUrl } = canonicalTargetsForTuple(qualified);
+  const commit = qualified.commit;
+  return Object.freeze({
+    schema: EXACT_GITHUB_SCHEMA_SOURCE_TARGET_SCHEMA_ID,
+    state: 'qualified',
+    repository: qualified.repository,
+    commit,
+    path: qualified.path,
+    blobUrl,
+    rawUrl,
+    targets: Object.freeze([blobUrl, rawUrl]),
+    findings: Object.freeze([])
+  });
+}
+
+export function qualifyExactGithubSchemaSourceTarget(candidate = '', sourceAuthority = null) {
+  const canonical = canonicalGithubSchemaSourceTargets(sourceAuthority);
+  const raw = String(candidate ?? '');
+  const target = raw === raw.trim() ? raw : '';
+  const index = canonical.state === 'qualified' ? canonical.targets.indexOf(target) : -1;
+  const qualified = index >= 0;
+  return Object.freeze({
+    schema: EXACT_GITHUB_SCHEMA_SOURCE_TARGET_SCHEMA_ID,
+    state: qualified ? 'qualified' : 'unavailable',
+    target: qualified ? canonical.targets[index] : '',
+    surface: qualified ? (index === 0 ? 'github-blob' : 'github-raw') : '',
+    canonical,
+    findings: Object.freeze([
+      ...(raw && raw !== raw.trim() ? ['Exact schema-source target must not contain outer whitespace.'] : []),
+      ...(canonical.state !== 'qualified' ? canonical.findings : []),
+      ...(canonical.state === 'qualified' && !qualified ? ['Candidate is not an exact canonical GitHub schema-source target.'] : [])
+    ])
+  });
+}
+
+export function qualifyGithubSchemaSourceProvider(binding = {}, sourceAuthority = null) {
+  const tuple = exactGithubSchemaSourceTuple(sourceAuthority);
+  if (!tuple) {
+    const sourceInputFindings = exactGithubSchemaSourceInputFindings(sourceAuthority);
+    return Object.freeze({ schema: GITHUB_SCHEMA_SOURCE_PROVIDER_QUALIFICATION_SCHEMA_ID, state: 'unavailable', provider: '', evidenceTarget: '', findings: Object.freeze(sourceInputFindings.length ? sourceInputFindings : ['Exact schema-source tuple is unavailable.']) });
+  }
+  const canonical = canonicalTargetsForTuple(tuple);
+  const declaredTargets = [binding?.permalink, binding?.rawUrl, binding?.exactReferenceTarget].map((item) => String(item ?? '')).filter(Boolean);
+  const evidenceTarget = declaredTargets.find((item) => canonical.targets.includes(item)) || '';
+  return Object.freeze({
+    schema: GITHUB_SCHEMA_SOURCE_PROVIDER_QUALIFICATION_SCHEMA_ID,
+    state: evidenceTarget ? 'qualified' : 'unavailable',
+    provider: evidenceTarget ? 'github' : '',
+    evidenceTarget,
+    repository: tuple.repository,
+    commit: tuple.commit,
+    path: tuple.path,
+    findings: Object.freeze(evidenceTarget ? [] : ['No explicit exact canonical GitHub source target qualifies this schema-source tuple as GitHub-backed.'])
+  });
+}
+
+function canonicalTargetsForTuple(qualified = {}) {
+  const path = (qualified.pathSegments || []).map(encodeExactGithubPathSegment).join('/');
+  const blobUrl = `https://github.com/${qualified.owner}/${qualified.repo}/blob/${qualified.commit}/${path}`;
+  const rawUrl = `https://raw.githubusercontent.com/${qualified.owner}/${qualified.repo}/${qualified.commit}/${path}`;
+  return Object.freeze({ blobUrl, rawUrl, targets: Object.freeze([blobUrl, rawUrl]) });
+}
+
+function exactGithubSchemaSourceIdentity(sourceAuthority = null) {
+  if (String(sourceAuthority?.provider || '').trim().toLowerCase() !== 'github') return null;
+  return exactGithubSchemaSourceTuple(sourceAuthority);
+}
+
+function exactGithubSchemaSourceTuple(sourceAuthority = null) {
+  const repository = String(sourceAuthority?.repository || '').trim();
+  const commit = String(sourceAuthority?.commit || '').trim();
+  const path = String(sourceAuthority?.path || '');
+  const repoParts = repository.split('/');
+  if (repoParts.length !== 2 || repoParts.some((part) => !/^[A-Za-z0-9_.-]+$/.test(part) || part === '.' || part === '..')) return null;
+  if (!/^[0-9a-f]{40}$/i.test(commit)) return null;
+  if (!path || !isWellFormedUnicodeScalarString(path) || path !== path.trim() || path.startsWith('/') || path.endsWith('/') || path.includes('\\') || /[\0\r\n?#]/.test(path)) return null;
+  const pathSegments = path.split('/');
+  if (!pathSegments.length || pathSegments.some((segment) => !segment || segment === '.' || segment === '..')) return null;
+  return Object.freeze({
+    repository: `${repoParts[0]}/${repoParts[1]}`,
+    owner: repoParts[0],
+    repo: repoParts[1],
+    commit: commit.toLowerCase(),
+    path,
+    pathSegments: Object.freeze(pathSegments)
+  });
+}
+
+function encodeExactGithubPathSegment(segment = '') {
+  const text = String(segment);
+  if (!isWellFormedUnicodeScalarString(text)) return '';
+  return encodeURIComponent(text).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function exactGithubSchemaSourceInputFindings(sourceAuthority = null) {
+  const path = String(sourceAuthority?.path || '');
+  if (path && !isWellFormedUnicodeScalarString(path)) return ['Exact GitHub schema-source path contains an unpaired UTF-16 surrogate and is not representable as a canonical URL target.'];
+  return [];
+}
+
+function isWellFormedUnicodeScalarString(value = '') {
+  const text = String(value);
+  for (let index = 0; index < text.length; index += 1) {
+    const unit = text.charCodeAt(index);
+    if (unit >= 0xD800 && unit <= 0xDBFF) {
+      const next = text.charCodeAt(index + 1);
+      if (!(next >= 0xDC00 && next <= 0xDFFF)) return false;
+      index += 1;
+      continue;
+    }
+    if (unit >= 0xDC00 && unit <= 0xDFFF) return false;
+  }
+  return true;
+}

package/src/schemas/schema.identity.js

@@ -0,0 +1,10 @@
+import { parseArtifactMarkdown } from '../artifacts/artifact.parse.js';
+
+export function schemaIdForRecord(record = {}, options = {}) {
+  const explicit = String(record?.schemaId || record?.currentSchemaId || record?.rootFallback?.currentSchemaId || '').trim();
+  if (explicit) return explicit;
+  const markdown = String(options.markdown ?? record?.markdown ?? '');
+  if (!markdown.trim()) return '';
+  try { return String(parseArtifactMarkdown(markdown).envelope?.current?.schema?.id || '').trim(); }
+  catch (_) { return ''; }
+}

package/src/schemas/schema.reference.js

@@ -0,0 +1,133 @@
+import { canonicalGithubSchemaSourceTargets } from './schema.githubSourceTarget.js';
+
+export const SCHEMA_REFERENCE_AUTHORITY_SCHEMA_ID = 'tiinex.site.schema-reference-authority.v1';
+export const SCHEMA_REFERENCE_MATERIAL_COHERENCE_SCHEMA_ID = 'tiinex.site.schema-reference-material-coherence.v1';
+
+export function schemaReferenceAuthorityFromBinding(schemaId = '', binding = {}, sourceAuthority = null, sourceQualification = null) {
+  const id = String(schemaId || binding?.schemaId || '').trim();
+  const localUnpublished = String(binding?.publicationState || '').toLowerCase().includes('unpublished');
+  const exactSourceTargets = localUnpublished
+    ? Object.freeze({ state: 'unavailable', targets: Object.freeze([]), findings: Object.freeze(['Binding is explicitly unpublished; remote source targets are not creation reference authority.']) })
+    : canonicalGithubSchemaSourceTargets(sourceAuthority);
+  const exactTargets = exactSourceTargets.state === 'qualified' ? [...exactSourceTargets.targets] : [];
+  const semanticMaterialIdentity = normalizeMaterialIdentity(sourceQualification?.materialIdentity || {});
+  const sourceQualified = sourceQualification?.state === 'qualified' && semanticMaterialIdentity.state === 'qualified';
+  const materialBoundTarget = Boolean(exactTargets.length && sourceQualified && sourceQualification?.bindingMaterialCoherence?.state === 'qualified');
+  const preferredTarget = exactTargets[0] || '';
+  return Object.freeze({
+    schema: SCHEMA_REFERENCE_AUTHORITY_SCHEMA_ID,
+    schemaId: id,
+    exactTargets: Object.freeze(exactTargets),
+    semanticSourceTargets: Object.freeze(exactTargets),
+    materialBoundTarget,
+    preferredTarget,
+    targetAuthority: exactTargets.length ? 'exact-source-target' : 'schema-id-only',
+    resolutionState: materialBoundTarget ? 'qualified' : exactTargets.length ? 'unresolved' : 'unavailable',
+    resolutionEvidence: Object.freeze(materialBoundTarget ? resolvedMaterialEvidence(preferredTarget, semanticMaterialIdentity) : {}),
+    semanticMaterialIdentity,
+    exactSourceTargets
+  });
+}
+
+export function qualifySchemaReferenceMaterialCoherence(authority = {}) {
+  const semantic = normalizeMaterialIdentity(authority?.semanticMaterialIdentity || {});
+  const target = String(authority?.preferredTarget || authority?.target || '').trim();
+  const directSourceTarget = authority?.materialBoundTarget === true;
+  const schemaIdOnly = !target && String(authority?.targetAuthority || '') === 'schema-id-only';
+  const resolutionEvidence = normalizeResolutionEvidence(authority?.resolutionEvidence || authority?.evidence || {}, target);
+  const evidence = resolutionEvidence.materialIdentity;
+  const findings = [];
+  if (semantic.state !== 'qualified') findings.push('Qualified semantic schema material identity is unavailable.');
+  let match = false;
+  let mode = 'unavailable';
+  if (semantic.state === 'qualified' && schemaIdOnly) {
+    match = true;
+    mode = 'schema-id-only-semantic-material';
+  } else if (semantic.state === 'qualified' && directSourceTarget) {
+    match = true;
+    mode = 'declared-source-target';
+  } else if (semantic.state === 'qualified' && resolutionEvidence.state === 'qualified' && evidence.state === 'qualified') {
+    match = materialIdentitiesMatch(semantic, evidence);
+    mode = match ? 'resolved-byte-equivalent-material' : 'resolved-material-mismatch';
+    if (!match) findings.push('Resolved schema-reference material does not match the semantic schema material used for exact creation.');
+  } else if (semantic.state === 'qualified') {
+    findings.push('Resolved schema-reference material identity is unavailable or not target-qualified; exact creation cannot bind the declared reference to the semantic schema material.');
+  }
+  if (!schemaIdOnly && authority?.resolutionState !== 'qualified') findings.push(`Declared schema reference resolver state is ${authority?.resolutionState || 'unavailable'}; exact creation requires qualified resolution.`);
+  return Object.freeze({ schema: SCHEMA_REFERENCE_MATERIAL_COHERENCE_SCHEMA_ID, state: findings.length || !match ? 'unavailable' : 'qualified', mode, target, semanticMaterialIdentity: semantic, resolverEvidence: resolutionEvidence, resolvedMaterialIdentity: evidence, findings: Object.freeze(findings) });
+}
+
+function normalizeMaterialIdentity(value = {}) {
+  const sha256 = String(value?.sha256 || value?.checksum || '').trim().toLowerCase();
+  const sourceBlobSha = String(value?.sourceBlobSha || value?.gitBlobSha || value?.blobSha || '').trim().toLowerCase();
+  const bytes = Number(value?.bytes || value?.byteLength || 0);
+  const schemaId = String(value?.schemaId || '').trim();
+  const qualified = value?.state === 'qualified' && Boolean(sha256 || sourceBlobSha);
+  return Object.freeze({ schema: String(value?.schema || 'tiinex.site.schema-material-identity.v1'), state: qualified ? 'qualified' : 'unavailable', schemaId, sha256, sourceBlobSha, bytes: Number.isFinite(bytes) && bytes > 0 ? bytes : 0, sourceRepository: String(value?.sourceRepository || ''), sourceCommit: String(value?.sourceCommit || ''), sourcePath: String(value?.sourcePath || '') });
+}
+
+function normalizeResolutionEvidence(value = {}, target = '') {
+  const declaredTarget = String(value?.target || value?.resolvedTarget || '').trim();
+  const state = String(value?.state || value?.qualification || '').trim();
+  const materialIdentity = normalizeResolvedMaterialIdentity(value?.materialIdentity || value?.material || {});
+  const qualified = state === 'qualified' && declaredTarget && declaredTarget === String(target || '').trim() && materialIdentity.state === 'qualified';
+  return Object.freeze({ state: qualified ? 'qualified' : 'unavailable', target: declaredTarget, materialIdentity, evidenceKind: String(value?.kind || value?.evidenceKind || '') });
+}
+
+function normalizeResolvedMaterialIdentity(value = {}) {
+  const sha256 = String(value?.sha256 || value?.checksum || value?.materialSha256 || '').trim().toLowerCase();
+  const sourceBlobSha = String(value?.sourceBlobSha || value?.gitBlobSha || value?.blobSha || '').trim().toLowerCase();
+  const bytes = Number(value?.bytes || value?.byteLength || 0);
+  return Object.freeze({ schema: 'tiinex.site.schema-material-identity.v1', state: sha256 || sourceBlobSha ? 'qualified' : 'unavailable', schemaId: String(value?.schemaId || ''), sha256, sourceBlobSha, bytes: Number.isFinite(bytes) && bytes > 0 ? bytes : 0, sourceRepository: String(value?.sourceRepository || value?.repository || ''), sourceCommit: String(value?.sourceCommit || value?.commit || ''), sourcePath: String(value?.sourcePath || value?.path || '') });
+}
+
+function resolvedMaterialEvidence(target = '', identity = {}) {
+  return Object.freeze({ state: 'qualified', target: String(target || ''), materialIdentity: Object.freeze({ state: 'qualified', sha256: String(identity?.sha256 || ''), gitBlobSha: String(identity?.sourceBlobSha || ''), bytes: Number(identity?.bytes || 0), sourceRepository: String(identity?.sourceRepository || ''), sourceCommit: String(identity?.sourceCommit || ''), sourcePath: String(identity?.sourcePath || '') }) });
+}
+
+function materialIdentitiesMatch(semantic = {}, resolved = {}) {
+  const cryptographic = [];
+  if (semantic.sha256 && resolved.sha256) cryptographic.push(semantic.sha256 === resolved.sha256);
+  if (semantic.sourceBlobSha && resolved.sourceBlobSha) cryptographic.push(semantic.sourceBlobSha === resolved.sourceBlobSha);
+  if (!cryptographic.length || cryptographic.some((match) => !match)) return false;
+  if (semantic.bytes && resolved.bytes && semantic.bytes !== resolved.bytes) return false;
+  return true;
+}
+
+export function parseSchemaReferenceValue(value = '') {
+  const raw = String(value ?? '');
+  if (!raw) return Object.freeze({ raw: '', form: 'empty', schemaId: '', target: '' });
+  const link = raw.match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  if (link) return Object.freeze({ raw, form: 'markdown-link', schemaId: link[1], target: link[2] });
+  return Object.freeze({ raw, form: 'plain-schema-id', schemaId: raw, target: '' });
+}
+
+export function renderSchemaReference(authority = {}) {
+  const schemaId = String(authority?.schemaId || '').trim();
+  if (!schemaId) throw new Error('schema-reference-id-missing');
+  const target = String(authority?.preferredTarget || '').trim();
+  return target ? `[${schemaId}](${target})` : schemaId;
+}
+
+export function qualifySchemaReferenceValue(value = '', authority = {}) {
+  const observed = parseSchemaReferenceValue(value);
+  const expectedSchemaId = String(authority?.schemaId || '').trim();
+  const exactTargets = new Set([...(authority?.exactTargets || [])].map((item) => String(item ?? '')).filter(Boolean));
+  const findings = [];
+  if (!expectedSchemaId) findings.push('Expected schema identifier authority is unavailable.');
+  if (observed.schemaId !== expectedSchemaId) findings.push(`Schema identifier must be exactly ${expectedSchemaId}; observed ${observed.schemaId || '(empty)'}.`);
+  let targetState = 'not-present';
+  if (observed.form === 'markdown-link') {
+    targetState = exactTargets.has(observed.target) ? 'qualified' : 'unqualified';
+    if (targetState !== 'qualified') findings.push(`Schema reference target is not qualified for ${expectedSchemaId}: ${observed.target || '(empty)'}.`);
+  }
+  if (observed.form === 'empty') findings.push('Schema reference value is empty.');
+  return Object.freeze({
+    state: findings.length ? 'unavailable' : 'qualified',
+    schemaIdState: observed.schemaId === expectedSchemaId && expectedSchemaId ? 'qualified' : 'unavailable',
+    targetState,
+    observed,
+    authority,
+    findings: Object.freeze(findings)
+  });
+}

package/src/schemas/schema.source.js

@@ -0,0 +1,239 @@
+import { sha256Hex, utf8Bytes } from '../export/package.bytes.js';
+import { qualifyGithubSchemaSourceProvider } from './schema.githubSourceTarget.js';
+
+export const BUNDLED_SCHEMA_SOURCE_SCHEMA_ID = 'tiinex.site.bundled-schema-source.v1';
+export const SCHEMA_RUNTIME_PROJECTION_SCHEMA_ID = 'tiinex.site.schema-runtime-projection.v1';
+export const SCHEMA_MATERIAL_IDENTITY_SCHEMA_ID = 'tiinex.site.schema-material-identity.v1';
+
+export function defineBundledSchemaSource(binding = {}, projection = {}, options = {}) {
+  const schemaId = String(binding?.schemaId || '').trim();
+  const expectedChecksum = String(binding?.checksum?.value || binding?.checksum || '').trim();
+  const baseAuthority = Object.freeze({
+    repository: String(binding?.sourceRepository || '').trim(),
+    commit: String(binding?.sourceCommit || '').trim(),
+    path: String(binding?.sourcePath || '').trim(),
+    blobSha: String(binding?.sourceBlobSha || '').trim(),
+    checksum: expectedChecksum
+  });
+  const providerQualification = qualifyGithubSchemaSourceProvider(binding, baseAuthority);
+  const authority = Object.freeze({
+    ...baseAuthority,
+    provider: providerQualification.state === 'qualified' ? providerQualification.provider : '',
+    providerQualification
+  });
+  const runtimeProjection = normalizeRuntimeProjection(projection);
+  let cached = null;
+  function qualify() {
+    if (cached) return cached;
+    const projectionExact = Boolean(
+      runtimeProjection.schema === SCHEMA_RUNTIME_PROJECTION_SCHEMA_ID
+      && schemaId
+      && expectedChecksum
+      && runtimeProjection.schemaId === schemaId
+      && runtimeProjection.sourceChecksum === expectedChecksum
+      && runtimeProjection.bindingChecksum === expectedChecksum
+    );
+    const bindingBlobSha = String(binding?.sourceBlobSha || '').trim().toLowerCase();
+    const loadedBlobSha = String(runtimeProjection.sourceBlobSha || '').trim().toLowerCase();
+    const snapshotCompleteness = String(binding?.snapshotCompleteness || '').trim();
+    const bindingMaterialCoherence = Object.freeze({
+      state: projectionExact && snapshotCompleteness === 'exact-canonical-docs-snapshot' && bindingBlobSha && bindingBlobSha === loadedBlobSha ? 'qualified' : 'unavailable',
+      bindingBlobSha,
+      loadedBlobSha,
+      snapshotCompleteness,
+      findings: Object.freeze([
+        ...(bindingBlobSha && loadedBlobSha && bindingBlobSha !== loadedBlobSha ? ['Binding sourceBlobSha does not match the Git-blob identity computed from the loaded schema bytes.'] : []),
+        ...(snapshotCompleteness !== 'exact-canonical-docs-snapshot' ? [`Binding snapshotCompleteness is ${snapshotCompleteness || 'unavailable'}; the external source target is not independently qualified as an exact canonical snapshot.`] : []),
+        ...(!bindingBlobSha ? ['Binding does not declare a sourceBlobSha that can be checked against the loaded schema bytes.'] : []),
+        ...(!loadedBlobSha ? ['Loaded schema Git-blob identity is unavailable from the runtime projection.'] : [])
+      ])
+    });
+    const validationContract = projectionExact && runtimeProjection.validationContract?.schemaId === schemaId && runtimeProjection.validationContract?.lineageQualification?.state === 'valid'
+      ? runtimeProjection.validationContract
+      : null;
+    const compiledContract = projectionExact ? Object.freeze({
+      schemaId,
+      validationContract,
+      creation: Object.freeze({
+        groups: Object.freeze((runtimeProjection.creation.groupNames || []).map((name) => Object.freeze({ name }))),
+        requiredInputs: runtimeProjection.creation.requiredInputs,
+        optionalInputs: runtimeProjection.creation.optionalInputs,
+        requiredSections: runtimeProjection.creation.requiredSections,
+        toolingConfigurationFields: runtimeProjection.creation.toolingConfigurationFields,
+        inputBindings: runtimeProjection.creation.inputBindings,
+        supplementalRequiredFields: runtimeProjection.creation.supplementalRequiredFields,
+        representationSections: deriveCreationRepresentationSections(runtimeProjection.creation.inputBindings, validationContract),
+        requiredShape: runtimeProjection.creation.requiredShape
+      })
+    }) : null;
+    const materialIdentity = Object.freeze({
+      schema: SCHEMA_MATERIAL_IDENTITY_SCHEMA_ID,
+      state: projectionExact ? 'qualified' : 'unavailable',
+      schemaId,
+      sha256: String(runtimeProjection.sourceChecksum || ''),
+      bytes: Number(runtimeProjection.sourceBytes || 0),
+      sourceRepository: String(authority.repository || ''),
+      sourceCommit: String(authority.commit || ''),
+      sourcePath: String(authority.path || ''),
+      sourceBlobSha: loadedBlobSha
+    });
+    cached = Object.freeze({
+      state: projectionExact ? 'qualified' : 'unavailable',
+      schemaId,
+      checksum: runtimeProjection.sourceChecksum || '',
+      expectedChecksum,
+      authority,
+      bindingMaterialCoherence,
+      materialIdentity,
+      compiledContract,
+      projection: runtimeProjection,
+      findings: Object.freeze([
+        ...(runtimeProjection.schema !== SCHEMA_RUNTIME_PROJECTION_SCHEMA_ID ? ['Schema runtime projection type is invalid.'] : []),
+        ...(runtimeProjection.schemaId !== schemaId ? ['Schema runtime projection identity does not match binding.'] : []),
+        ...(runtimeProjection.sourceChecksum !== expectedChecksum ? ['Schema runtime projection source checksum does not match binding.'] : []),
+        ...(runtimeProjection.bindingChecksum !== expectedChecksum ? ['Schema runtime projection binding checksum does not match binding.'] : []),
+        ...(runtimeProjection.validationContract && runtimeProjection.validationContract?.schemaId !== schemaId ? ['Schema runtime validation projection identity does not match binding.'] : []),
+        ...(runtimeProjection.validationContract && runtimeProjection.validationContract?.lineageQualification?.state !== 'valid' ? ['Schema runtime validation projection lineage is not exact/valid.'] : [])
+      ])
+    });
+    return cached;
+  }
+  return Object.freeze({
+    schema: BUNDLED_SCHEMA_SOURCE_SCHEMA_ID,
+    status: schemaId && expectedChecksum && runtimeProjection.schemaId ? 'bundled' : 'unavailable',
+    readable: Boolean(schemaId && options.assetUrl),
+    schemaId,
+    markdown: '',
+    bundledPath: String(options.bundledPath || binding?.sourcePath || '').trim(),
+    sourceLabel: String(options.sourceLabel || 'Viewer schema registry').trim(),
+    assetUrl: String(options.assetUrl || '').trim(),
+    expectedChecksum,
+    authority,
+    runtimeProjection,
+    qualify
+  });
+}
+
+export function qualifyBundledSchemaSource(source = null) {
+  return typeof source?.qualify === 'function'
+    ? source.qualify()
+    : Object.freeze({ state: 'unavailable', schemaId: String(source?.schemaId || ''), compiledContract: null, findings: Object.freeze(['Schema source qualification owner is unavailable.']) });
+}
+
+export function qualifyBundledSchemaReadableText(source = null, markdown = '') {
+  const sourceQualification = qualifyBundledSchemaSource(source);
+  const text = String(markdown ?? '');
+  const checksum = text ? sha256Hex(utf8Bytes(text)) : '';
+  const exact = Boolean(
+    sourceQualification.state === 'qualified'
+    && text
+    && checksum === String(source?.expectedChecksum || '')
+    && checksum === String(sourceQualification.checksum || '')
+  );
+  return Object.freeze({
+    state: exact ? 'qualified' : 'unavailable',
+    schemaId: String(source?.schemaId || ''),
+    checksum,
+    expectedChecksum: String(source?.expectedChecksum || ''),
+    authority: source?.authority || null,
+    markdown: exact ? text : '',
+    sourceQualification,
+    findings: Object.freeze([
+      ...(!text ? ['Bundled schema readable source is empty.'] : []),
+      ...(text && checksum !== String(source?.expectedChecksum || '') ? ['Bundled schema readable source checksum does not match binding.'] : [])
+    ])
+  });
+}
+
+export function qualifiedCreationAuthorityFromSchemaSource(module = {}) {
+  const source = module?.schemaSource || null;
+  const binding = module?.binding || {};
+  const schemaId = String(module?.id || '').trim();
+  const qualification = qualifyBundledSchemaSource(source);
+  const compiled = qualification?.compiledContract || null;
+  const exact = Boolean(
+    qualification?.state === 'qualified'
+    && schemaId
+    && String(qualification.schemaId || '') === schemaId
+    && String(binding.schemaId || '') === schemaId
+    && String(qualification.checksum || '')
+    && String(qualification.checksum || '') === String(binding.checksum?.value || binding.checksum || '')
+    && String(qualification.authority?.path || '') === String(binding.sourcePath || '')
+    && String(qualification.authority?.commit || '') === String(binding.sourceCommit || '')
+    && String(compiled?.schemaId || '') === schemaId
+  );
+  const creationGroups = exact && Array.isArray(compiled?.creation?.groups) ? compiled.creation.groups : [];
+  const declared = creationGroups.length > 0;
+  return Object.freeze({
+    state: exact && declared ? 'qualified' : 'unavailable',
+    schemaId,
+    contractSection: 'Artifact Creation Contract',
+    sourceStatus: qualification?.state || 'unavailable',
+    checksum: String(qualification?.checksum || ''),
+    sourcePath: String(qualification?.authority?.path || ''),
+    sourceRepository: String(qualification?.authority?.repository || ''),
+    sourceCommit: String(qualification?.authority?.commit || ''),
+    compiledContract: exact ? compiled : null,
+    contractDeclared: declared
+  });
+}
+
+
+function deriveCreationRepresentationSections(inputBindings = [], validationContract = null) {
+  void validationContract;
+  const ordered = [];
+  for (const item of inputBindings || []) {
+    const name = String(item?.section || '').trim();
+    if (name && !ordered.includes(name)) ordered.push(name);
+  }
+  return Object.freeze(ordered);
+}
+
+function normalizeRuntimeProjection(value = {}) {
+  const creation = value?.creation || {};
+  return Object.freeze({
+    schema: String(value?.schema || ''),
+    generator: String(value?.generator || ''),
+    schemaId: String(value?.schemaId || '').trim(),
+    sourceChecksum: String(value?.sourceChecksum || '').trim(),
+    sourceBlobSha: String(value?.sourceBlobSha || '').trim(),
+    sourceBytes: Number(value?.sourceBytes || 0),
+    bindingChecksum: String(value?.bindingChecksum || '').trim(),
+    validationContract: freezeRuntimeValidationContract(value?.validationContract || {}),
+    creation: Object.freeze({
+      declared: Boolean(creation?.declared),
+      groupNames: Object.freeze([...(creation?.groupNames || [])].map((item) => String(item || '')).filter(Boolean)),
+      requiredInputs: Object.freeze([...(creation?.requiredInputs || [])].map((item) => String(item || '')).filter(Boolean)),
+      optionalInputs: Object.freeze([...(creation?.optionalInputs || [])].map((item) => String(item || '')).filter(Boolean)),
+      requiredSections: Object.freeze([...(creation?.requiredSections || [])].map((item) => String(item || '')).filter(Boolean)),
+      toolingConfigurationFields: Object.freeze([...(creation?.toolingConfigurationFields || [])].map((item) => String(item || '')).filter(Boolean)),
+      inputBindings: Object.freeze([...(creation?.inputBindings || [])].map((item) => deepFreezeJson(item)).filter((item) => String(item?.input || '').trim())),
+      supplementalRequiredFields: Object.freeze([...(creation?.supplementalRequiredFields || [])].map((item) => deepFreezeJson(item)).filter((item) => String(item?.field || '').trim())),
+      requiredShape: Object.freeze([...(creation?.requiredShape || [])].map((item) => Object.freeze({ id: String(item?.id || ''), sourceSchemaId: String(item?.sourceSchemaId || ''), group: String(item?.group || ''), category: String(item?.category || ''), line: Number(item?.line || 0), sourceText: String(item?.sourceText || ''), primitive: Object.freeze({ kind: String(item?.primitive?.kind || 'residual'), input: String(item?.primitive?.input || ''), section: String(item?.primitive?.section || ''), position: String(item?.primitive?.position || '') }) })).filter((item) => item.id))
+    })
+  });
+}
+
+
+function freezeRuntimeValidationContract(value = {}) {
+  return deepFreezeJson({
+    schema: String(value?.schema || ''),
+    schemaId: String(value?.schemaId || '').trim(),
+    lineage: Array.isArray(value?.lineage) ? value.lineage : [],
+    lineageQualification: value?.lineageQualification || {},
+    lineageAuthority: Array.isArray(value?.lineageAuthority) ? value.lineageAuthority : [],
+    inheritanceResolution: value?.inheritanceResolution || {},
+    validation: value?.validation || {},
+    declarations: Array.isArray(value?.declarations) ? value.declarations : [],
+    constraints: Array.isArray(value?.constraints) ? value.constraints : [],
+    machineShapes: value?.machineShapes || {}
+  });
+}
+
+function deepFreezeJson(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return Object.freeze(value.map(deepFreezeJson));
+  const out = {};
+  for (const [key, item] of Object.entries(value)) out[key] = deepFreezeJson(item);
+  return Object.freeze(out);
+}