@tiinex/app 0.1.1

package/src/adapters/github/github.issueTransport.js

@@ -0,0 +1,237 @@
+import { createGithubTransportFetch, normalizeGithubTransportTier } from '../../sources/github/github.transport.js';
+import { createGithubIssueSnapshotRecords, githubIssueFetchWarning, parseGithubIssueSnapshotTarget, parseGithubIssueSnapshotTargets } from './github.issueSnapshot.js';
+
+export function finding(severity, code, message, extra = {}) { return Object.assign({ severity, code, message }, extra); }
+
+export function issueMirrorFetchForTier(source = {}, tier = '', fetchImpl, diagnostics = {}) {
+  const normalized = normalizeGithubTransportTier(tier);
+  if (normalized !== 'mirror' && normalized !== 'cache') return fetchImpl;
+  return async (url, init = {}) => {
+    const emit = (event) => diagnostics.transportEvents?.push?.(Object.assign({ adapterId: 'github', sourceId: source?.id || '', repo: source?.repo || source?.repository || '', tier: normalized, resource: 'api-json', url }, event));
+    if (!fetchImpl && normalized !== 'cache') {
+      emit({ code: `github.transport.${normalized}.unavailable`, severity: 'warning', message: 'Hosted issue snapshot mirror fetch is unavailable in this runtime.' });
+      return responseWithTransport(null, normalized);
+    }
+    emit({ code: `github.transport.${normalized}.try`, severity: 'info', url, resource: 'api-json' });
+    try {
+      const res = await fetchImpl(url, init);
+      if (res?.ok) emit({ code: `github.transport.${normalized}.ok`, severity: 'info', url, resource: 'api-json', status: res.status || 200 });
+      else emit({ code: `github.transport.${normalized}.failed`, severity: 'warning', url, resource: 'api-json', status: res?.status || 0, message: res?.statusText || '' });
+      return responseWithTransport(res, normalized);
+    } catch (error) {
+      emit({ code: `github.transport.${normalized}.exception`, severity: 'warning', message: error?.message || String(error || '') });
+      throw error;
+    }
+  };
+}
+
+export function issueApiFetchForTier(source = {}, tier = '', fetchImpl, diagnostics = {}, options = {}) {
+  const normalized = normalizeGithubTransportTier(tier);
+  if (normalized !== 'proxy') return fetchImpl;
+  const apiFetch = options.proxyFetchImpl || fetchImpl;
+  const emit = (event) => diagnostics.transportEvents?.push?.(Object.assign({ adapterId: 'github', sourceId: source?.id || '', repo: source?.repo || source?.repository || '', tier: 'proxy', resource: 'github-api-json' }, event));
+  if (!apiFetch) {
+    return async () => {
+      emit({ code: 'github.transport.proxy.unavailable', severity: 'warning', message: 'Proxy/API issue reader is unavailable in this runtime.' });
+      return responseWithTransport(null, 'proxy');
+    };
+  }
+  const runtime = createGithubTransportFetch(source, Object.assign({}, options, {
+    fetchImpl: apiFetch,
+    transportPlan: undefined,
+    preferredTransports: ['direct'],
+    transportOrderExact: true,
+    allowCache: false,
+    onTransportEvent: (event = {}) => emit(Object.assign({}, event, {
+      tier: 'proxy',
+      code: String(event.code || '').replace('github.transport.direct.', 'github.transport.proxy.')
+    }))
+  }));
+  return async (url, init = {}) => {
+    const res = await runtime.fetch(url, init);
+    return responseWithTransport(res, 'proxy', true);
+  };
+}
+
+
+export function directIssueDiscoveryUnavailable(source = {}, diagnostics = {}) {
+  const repo = source?.repo || source?.repository || '';
+  const warning = finding('warning', 'github.issue.direct.discovery-unavailable', 'Direct issue transport does not perform repository-wide issue discovery. Provide explicit issue URLs, use hosted mirror, or use proxy/API transport.', { surface: 'issueSnapshots', repo, transportTier: 'direct' });
+  diagnostics.transportEvents?.push?.({ adapterId: 'github', sourceId: source?.id || '', repo, tier: 'direct', resource: 'issue-raw', code: 'github.transport.direct.discovery-unavailable', severity: 'warning', message: warning.message });
+  return { schema: 'tiinex.github.issueSnapshot.discovery.v1', status: 'unavailable', targets: [], warnings: [warning], errors: [], counts: { discovered: 0, targets: 0, warnings: 1, errors: 0 }, transportTier: 'direct' };
+}
+
+export async function materializeDirectIssueTargets(targets = [], source = {}, options = {}, diagnostics = {}) {
+  const parsed = Array.isArray(targets) ? { targets, errors: [], counts: { targets: targets.length, errors: 0 } } : parseGithubIssueSnapshotTargets(targets || []);
+  const records = [];
+  const warnings = [];
+  const errors = [...(parsed.errors || [])];
+  const targetResults = [];
+  const fetchImpl = options.fetchImpl;
+  if (!fetchImpl) {
+    const warning = finding('warning', 'github.issue.direct.reader-unavailable', 'Direct issue transport has no raw fetch implementation in this runtime.', { surface: 'issueSnapshots', transportTier: 'direct' });
+    warnings.push(warning);
+    return { schema: 'tiinex.github.issueSnapshot.materialization.v1', records, warnings, errors, targetResults, counts: issueSurfaceMaterializationCounts(parsed.counts.targets, 0, warnings.length, errors.length, targetResults), transportTier: 'direct' };
+  }
+  for (const target of parsed.targets || []) {
+    const normalized = target.ok ? target : parseGithubIssueSnapshotTarget(target.canonicalUrl || target.html_url || target.url || '');
+    if (!normalized.ok) {
+      errors.push({ ref: target.input || target.url || '', error: normalized.error || 'invalid issue target' });
+      targetResults.push(issueSurfaceTargetResult(target, { status: 'failed', warningCode: 'invalid-issue-target', message: normalized.error || 'invalid issue target', transportTier: 'direct' }));
+      continue;
+    }
+    try {
+      const directUrl = normalized.directRawUrl || normalized.canonicalUrl;
+      const res = await fetchImpl(directUrl, { headers: { Accept: 'text/markdown,text/plain,text/html,application/json,*/*' } });
+      if (!res?.ok) {
+        const warning = githubIssueFetchWarning(Object.assign(new Error(`${res?.status || 0} ${res?.statusText || ''}`.trim()), { status: res?.status || 0, statusText: res?.statusText || '', url: directUrl }), 'github.issue.direct.fetch-failed', `Direct raw issue fetch could not read ${directUrl}; no GitHub API request was made. Normal github.com issue pages may be blocked by browser CORS unless the URL is a browser-readable raw/static snapshot.`, { transportTier: 'direct' });
+        warnings.push(warning);
+        targetResults.push(issueSurfaceTargetResult(normalized, { status: 'failed', warningCode: warning.code, message: warning.message, transportTier: 'direct' }));
+        continue;
+      }
+      const body = await res.text();
+      const issue = directIssueSnapshotFromRawBody(body, normalized);
+      const issueRecords = createGithubIssueSnapshotRecords(Object.assign({
+        target: normalized,
+        html_url: normalized.canonicalUrl,
+        number: normalized.number,
+        title: `Issue #${normalized.number}`,
+        state: '',
+        body,
+        user: { login: '' },
+        comments: [],
+        method: 'github-direct-raw-issue-reader'
+      }, issue || {}), options);
+      for (const record of issueRecords) {
+        record.sourceTarget = Object.assign({
+          schema: 'tiinex.source.material.target.v1',
+          surface: 'issueSnapshots',
+          targetKind: record.snapshot?.embedded ? `github-${normalized.kind}-embedded-artifact` : `github-${normalized.kind}-snapshot`,
+          inputTarget: record.snapshot?.sourceUrl || normalized.canonicalUrl,
+          transportTier: 'direct',
+          loaded: true
+        }, record.sourceTarget || {});
+        records.push(record);
+      }
+      targetResults.push(issueSurfaceTargetResult(normalized, { status: 'loaded', records: issueRecords.length, transportTier: 'direct' }));
+    } catch (error) {
+      const warning = githubIssueFetchWarning(error, 'github.issue.direct.fetch-exception', `Direct raw issue fetch could not read ${normalized.canonicalUrl}; no GitHub API request was made.`, { url: normalized.canonicalUrl, transportTier: 'direct' });
+      warnings.push(warning);
+      targetResults.push(issueSurfaceTargetResult(normalized, { status: 'failed', warningCode: warning.code, message: warning.message, transportTier: 'direct' }));
+    }
+  }
+  return { schema: 'tiinex.github.issueSnapshot.materialization.v1', records, warnings, errors, targetResults, counts: issueSurfaceMaterializationCounts(parsed.counts.targets, records.length, warnings.length, errors.length, targetResults), transportTier: 'direct' };
+}
+
+
+function directIssueSnapshotFromRawBody(body = '', target = {}) {
+  if (String(target.directRawFormat || '').toLowerCase() !== 'json') return null;
+  try {
+    const parsed = JSON.parse(String(body || '{}'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return Object.assign({}, parsed, {
+      target,
+      body: parsed.body || parsed.markdown || parsed.content || '',
+      comments: Array.isArray(parsed.comments) ? parsed.comments : [],
+      method: 'github-direct-static-issue-json'
+    });
+  } catch (_) {
+    return null;
+  }
+}
+
+function issueSurfaceMaterializationCounts(targets = 0, records = 0, warnings = 0, errors = 0, targetResults = []) {
+  const results = Array.isArray(targetResults) ? targetResults : [];
+  return {
+    targets,
+    records,
+    warnings,
+    errors,
+    loadedTargets: results.filter((item) => item.status === 'loaded').length,
+    failedTargets: results.filter((item) => item.status === 'failed').length,
+    deferredTargets: results.filter((item) => item.status === 'deferred').length
+  };
+}
+
+function issueSurfaceTargetResult(target = {}, patch = {}) {
+  const number = Number(target.number || 0);
+  const canonicalUrl = target.canonicalUrl || target.html_url || target.url || target.input || '';
+  return Object.assign({
+    schema: 'tiinex.github.issueSnapshot.targetResult.v1',
+    repository: target.repository || (target.owner && target.repo ? `${target.owner}/${target.repo}` : ''),
+    kind: target.kind || 'issue',
+    number: Number.isFinite(number) ? number : 0,
+    url: canonicalUrl,
+    status: 'pending',
+    records: 0,
+    transportTier: '',
+    warningCode: '',
+    message: ''
+  }, patch || {});
+}
+
+export function issueDirectFetchForTier(source = {}, fetchImpl, diagnostics = {}) {
+  return async (url, init = {}) => {
+    const emit = (event) => diagnostics.transportEvents?.push?.(Object.assign({ adapterId: 'github', sourceId: source?.id || '', repo: source?.repo || source?.repository || '', tier: 'direct', resource: 'issue-raw', url }, event));
+    if (!fetchImpl) {
+      emit({ code: 'github.transport.direct.unavailable', severity: 'warning', message: 'Direct issue raw fetch is unavailable in this runtime.' });
+      return responseWithTransport(null, 'direct');
+    }
+    emit({ code: 'github.transport.direct.try', severity: 'info' });
+    try {
+      const res = await fetchImpl(url, init);
+      if (res?.ok) emit({ code: 'github.transport.direct.ok', severity: 'info', status: res.status || 200 });
+      else emit({ code: 'github.transport.direct.failed', severity: 'warning', status: res?.status || 0, message: res?.statusText || '' });
+      return responseWithTransport(res, 'direct');
+    } catch (error) {
+      emit({ code: 'github.transport.direct.exception', severity: 'warning', message: error?.message || String(error || '') });
+      throw error;
+    }
+  };
+}
+
+export function responseWithTransport(res, tier = '', forceTier = false) {
+  // Native Response fields are brand-checked accessors. Keep an ordinary
+  // delegating object rather than prototype-shelling real Fetch responses.
+  if (!res) return makeTransportResponse('', { ok: false, status: 503, statusText: 'Transport unavailable', tier, contentType: 'application/json' });
+  if (res.transportTier && !forceTier) return res;
+  const status = Number(res.status || 0) || (res.ok ? 200 : 500);
+  const ok = res.ok !== false && status >= 200 && status < 300;
+  const headers = res.headers || { get: () => null };
+  return Object.freeze({
+    ok,
+    status,
+    statusText: res.statusText || (ok ? 'OK' : 'Error'),
+    url: res.url || '',
+    transportTier: tier,
+    headers: { get: (name) => headers.get?.(name) ?? null },
+    text: async () => {
+      if (typeof res.clone === 'function') return res.clone().text();
+      if (typeof res.text === 'function') return res.text();
+      return String(res.body || '');
+    },
+    json: async () => {
+      if (typeof res.clone === 'function') return res.clone().json();
+      if (typeof res.json === 'function') return res.json();
+      return JSON.parse(String(res.body || '{}'));
+    },
+    clone: () => responseWithTransport(typeof res.clone === 'function' ? res.clone() : res, tier)
+  });
+}
+
+export function makeTransportResponse(body = '', options = {}) {
+  const text = String(body || '');
+  const status = Number(options.status || 0) || (options.ok === false ? 503 : 200);
+  const ok = options.ok !== false && status >= 200 && status < 300;
+  return Object.freeze({
+    ok,
+    status,
+    statusText: options.statusText || (ok ? 'OK' : 'Error'),
+    url: options.url || '',
+    transportTier: options.tier || '',
+    headers: { get: (name) => String(name || '').toLowerCase() === 'content-type' ? (options.contentType || 'application/json') : null },
+    text: async () => text,
+    json: async () => JSON.parse(text || '{}'),
+    clone: () => makeTransportResponse(text, options)
+  });
+}

package/src/adapters/github/github.publicationRead.js

@@ -0,0 +1,24 @@
+import { fetchGithubJson } from './github.readTransport.js';
+export async function readExactGithubIssuePublicationRepresentation(exactTarget = {}, options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!fetchImpl) throw new Error('github-publication-verification-fetch-unavailable');
+  if (!exactTarget?.ok || exactTarget?.provider !== 'github' || !exactTarget?.owner || !exactTarget?.repo || !exactTarget?.issueNumber) throw new Error('github-publication-verification-target-unqualified');
+  const comment = exactTarget.targetKind === 'github.issue.comment';
+  const url = comment
+    ? `https://api.github.com/repos/${exactTarget.owner}/${exactTarget.repo}/issues/comments/${encodeURIComponent(String(exactTarget.commentId || ''))}`
+    : `https://api.github.com/repos/${exactTarget.owner}/${exactTarget.repo}/issues/${exactTarget.issueNumber}`;
+  if (comment && !exactTarget.commentId) throw new Error('github-publication-verification-comment-id-missing');
+  const body = await fetchGithubJson(url, fetchImpl);
+  return Object.freeze({
+    schema: 'tiinex.github.publicationVerificationObservation.v1',
+    targetKind: exactTarget.targetKind,
+    inputTarget: exactTarget.inputTarget,
+    issueTarget: exactTarget.issueTarget,
+    content: String(body?.body || ''),
+    providerReceiptId: String(body?.id || (comment ? exactTarget.commentId : exactTarget.issueNumber)),
+    observedAt: String(body?.updated_at || body?.created_at || ''),
+    method: comment ? 'github-browser-issue-reader-exact-comment-body' : 'github-browser-issue-reader-exact-issue-body',
+    transportTier: String(body?.transportTier || ''),
+    boundary: 'Read-only body observation over a target already qualified by the shared exact GitHub social target authority; this owner does not parse publication target strings or mutate GitHub.'
+  });
+}

package/src/adapters/github/github.readTransport.js

@@ -0,0 +1,18 @@
+export async function fetchGithubJson(url, fetchImpl) {
+  if (typeof fetchImpl !== 'function') throw new Error('github-read-fetch-unavailable');
+  const res = await fetchImpl(url, { headers: { Accept: 'application/vnd.github+json' } });
+  if (!res || !res.ok) {
+    const status = res?.status || 0;
+    const statusText = res?.statusText || '';
+    let bodyMessage = '';
+    try { const body = await res.json(); bodyMessage = body?.message ? String(body.message) : ''; } catch (_) {}
+    const err = new Error([status ? `GitHub API ${status}` : 'GitHub API', statusText, bodyMessage].filter(Boolean).join(' ').trim() || 'GitHub API request failed');
+    err.status = status;
+    err.statusText = statusText;
+    err.url = url;
+    throw err;
+  }
+  const body = await res.json();
+  if (body && typeof body === 'object' && !Array.isArray(body)) body.transportTier = res.transportTier || '';
+  return body;
+}

package/src/adapters/github/github.repoDiscovery.js

@@ -0,0 +1,222 @@
+import { governanceBoundaryFromRootFiles, isGovernanceNoticePath, isGovernancePolicyPath } from '@tiinex/core/governance/governance.boundary.js';
+
+const MARKDOWN_EXTENSIONS = /\.(md|markdown|trace\.md|schema\.md|validator\.md|workspace\.md)$/i;
+
+function repoParts(source = {}) {
+  const repo = String(source.repo || source.repository || '').trim();
+  const parts = repo.split('/').filter(Boolean);
+  if (parts.length < 2) throw new Error('source.repo missing or invalid');
+  return { repo: `${parts[0]}/${parts[1]}`, owner: parts[0], name: parts[1] };
+}
+
+function rootPaths(source = {}) {
+  return String(source.rootPath || '')
+    .split(/\r?\n|,/)
+    .map((item) => item.trim().replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, ''))
+    .filter((item) => item && item !== '.');
+}
+
+function underRoots(path, roots) {
+  if (!roots.length) return true;
+  return roots.some((root) => path === root || path.startsWith(root + '/'));
+}
+
+function isMarkdownPath(path) {
+  return MARKDOWN_EXTENSIONS.test(String(path || ''));
+}
+
+export function githubWorkspaceMatchPatterns(source = {}, input = {}) {
+  return String(input.workspaceMatch || source.workspaceMatch || source.match || '')
+    .split(/\r?\n|,/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function matchesGithubWorkspacePattern(path = '', patterns = []) {
+  const clean = String(path || '').replace(/^\/+/, '').replace(/\\/g, '/');
+  if (!patterns || !patterns.length) return true;
+  const name = clean.split('/').filter(Boolean).pop() || clean;
+  return patterns.some((pattern) => {
+    const raw = String(pattern || '').trim().replace(/^\.\//, '');
+    if (!raw) return true;
+    const target = raw.includes('/') ? clean : name;
+    return globToRegExp(raw).test(target);
+  });
+}
+
+function globToRegExp(pattern = '') {
+  const source = String(pattern || '')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]')
+    .replace(/\u0000/g, '.*');
+  return new RegExp(`^${source}$`, 'i');
+}
+
+async function fetchJson(url, fetchImpl) {
+  const res = await fetchImpl(url, { headers: { Accept: 'application/vnd.github+json' } });
+  if (!res || !res.ok) {
+    const status = res?.status || 'ERR';
+    const statusText = res?.statusText || '';
+    let bodyMessage = '';
+    try {
+      const body = await res.json();
+      bodyMessage = body?.message ? String(body.message) : '';
+    } catch (error) {
+      bodyMessage = '';
+    }
+    const message = [String(status), statusText, bodyMessage].filter(Boolean).join(' ').trim();
+    const err = new Error(message || 'GitHub API request failed');
+    err.status = status;
+    err.statusText = statusText;
+    err.url = url;
+    return Promise.reject(err);
+  }
+  return res.json();
+}
+
+export async function resolveGithubSourceRef(source, options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!fetchImpl) throw new Error('fetchImpl not available');
+  const explicit = String(source?.ref || '').trim();
+  if (explicit) return { ref: explicit, resolvedBy: 'source.ref' };
+  const { owner, name } = repoParts(source);
+  const data = await fetchJson(`https://api.github.com/repos/${owner}/${name}`, fetchImpl);
+  const ref = String(data.default_branch || '').trim();
+  if (!ref) throw new Error('default branch unavailable');
+  return { ref, resolvedBy: 'github.repo.default_branch' };
+}
+
+export function exactGithubCommit(value = '') { const commit = String(value || '').trim(); return /^[0-9a-f]{40}$/i.test(commit) ? commit : ''; }
+
+export function githubRefResolutionRequestCount(source = {}) {
+  if (exactGithubCommit(source?.materializedCommit)) return 0;
+  const ref = String(source?.ref || '').trim();
+  if (!ref) return 2;
+  return exactGithubCommit(ref) ? 0 : 1;
+}
+
+export function githubRepoDiscoveryRequestCount(source = {}) {
+  return githubRefResolutionRequestCount(source) + 1;
+}
+
+export async function resolveGithubMaterializedCommit(source, ref = '', options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!fetchImpl) throw new Error('fetchImpl not available');
+  const selectedRef = String(ref || source?.ref || '').trim();
+  const resolved = selectedRef ? { ref: selectedRef, resolvedBy: 'source.ref' } : await resolveGithubSourceRef(source, { fetchImpl });
+  if (exactGithubCommit(resolved.ref)) return { ...resolved, commit: resolved.ref, commitResolvedBy: 'source.ref.exact-commit' };
+  const { owner, name } = repoParts(source);
+  const data = await fetchJson(`https://api.github.com/repos/${owner}/${name}/commits/${encodeURIComponent(resolved.ref)}`, fetchImpl);
+  const commit = String(data.sha || '').trim();
+  if (!exactGithubCommit(commit)) throw new Error('resolved GitHub commit unavailable');
+  return { ...resolved, commit, commitResolvedBy: 'github.commit-resolution' };
+}
+
+
+export async function tryResolveGithubMaterializedCommit(source, ref = '', options = {}) {
+  try { return exactGithubCommit((await resolveGithubMaterializedCommit(source, ref, options)).commit); }
+  catch (_) { return ''; }
+}
+
+export async function discoverGithubMarkdownRefs(source, options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!fetchImpl) throw new Error('fetchImpl not available');
+  const maxFiles = Math.max(1, Number(options.maxFiles || 500));
+  const { owner, name } = repoParts(source);
+  const prequalifiedCommit = exactGithubCommit(source?.materializedCommit);
+  const configuredRef = String(source?.ref || '').trim();
+  const resolved = prequalifiedCommit
+    ? { ref: configuredRef, resolvedBy: configuredRef ? 'source.ref' : 'source.materializedCommit.prequalified' }
+    : await resolveGithubSourceRef(source, { fetchImpl });
+  const materializedCommit = prequalifiedCommit || await tryResolveGithubMaterializedCommit(source, resolved.ref, { fetchImpl });
+  const treeRef = materializedCommit || resolved.ref;
+  const treeUrl = `https://api.github.com/repos/${owner}/${name}/git/trees/${encodeURIComponent(treeRef)}?recursive=1`;
+  const tree = await fetchJson(treeUrl, fetchImpl);
+  const roots = rootPaths(source);
+  const patterns = githubWorkspaceMatchPatterns(source, options);
+  const refs = [];
+  const warnings = [];
+  const governanceRootFiles = [];
+  for (const item of Array.isArray(tree.tree) ? tree.tree : []) {
+    const path = String(item.path || '').replace(/^\/+/, '');
+    if (item.type !== 'blob') continue;
+    if (!path.includes('/') && (isGovernancePolicyPath(path) || isGovernanceNoticePath(path))) governanceRootFiles.push({ path, kind: path });
+    if (!underRoots(path, roots)) continue;
+    if (!isMarkdownPath(path)) continue;
+    if (!matchesGithubWorkspacePattern(path, patterns)) continue;
+    if (refs.length < maxFiles) refs.push(path);
+  }
+  refs.sort((a, b) => a.localeCompare(b));
+  if (tree.truncated) warnings.push({ code: 'github.tree.truncated', message: 'GitHub tree response was truncated.' });
+  const totalMarkdown = (Array.isArray(tree.tree) ? tree.tree : []).filter((item) => item.type === 'blob' && underRoots(String(item.path || ''), roots) && isMarkdownPath(item.path) && matchesGithubWorkspacePattern(String(item.path || ''), patterns)).length;
+  if (totalMarkdown > refs.length) warnings.push({ code: 'github.discovery.bounded', message: `Loaded first ${refs.length} of ${totalMarkdown} markdown files.` });
+  return { refs, warnings, ref: resolved.ref, resolvedBy: resolved.resolvedBy, materializedCommit, treeUrl, totalMarkdown, governanceBoundary: governanceBoundaryFromRootFiles(Object.assign({}, source, { ref: materializedCommit || resolved.ref }), governanceRootFiles, { rootChecked: true, discoveredFrom: 'github-tree-root-manifest' }) };
+}
+
+export function qualifyGithubSnapshotInput(source = {}, input = '') {
+  const target = String(input || '').trim();
+  if (!target) return snapshotFailure('github.snapshot.input.required', 'Enter an exact commit, GitHub tree/commit URL, or explicit ref.');
+  let configured;
+  try { configured = repoParts(source); }
+  catch (_) { return snapshotFailure('github.snapshot.source.unsupported', 'A configured GitHub repository source is required.'); }
+
+  if (exactGithubCommit(target)) return snapshotQualification(configured.repo, target, target, 'explicit-commit');
+
+  if (/^https?:\/\//i.test(target)) {
+    let url;
+    try { url = new URL(target); }
+    catch (_) { return snapshotFailure('github.snapshot.target.malformed', 'Snapshot target URL is malformed.'); }
+    if (url.hostname.toLowerCase() !== 'github.com') return snapshotFailure('github.snapshot.target.unsupported-host', 'Snapshot target must use github.com.');
+    const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+    if (parts.length < 4) return snapshotFailure('github.snapshot.target.unsupported', 'Use a GitHub commit or tree URL.');
+    const repository = `${parts[0]}/${String(parts[1] || '').replace(/\.git$/i, '')}`;
+    if (repository.toLowerCase() !== configured.repo.toLowerCase()) return snapshotFailure('github.snapshot.repository.mismatch', 'Snapshot target must belong to the configured source repository.');
+    const kind = String(parts[2] || '').toLowerCase();
+    if (kind === 'commit') {
+      const commit = exactGithubCommit(parts[3]);
+      return commit
+        ? snapshotQualification(repository, commit, target, 'github-commit-url')
+        : snapshotFailure('github.snapshot.commit-url.exact-required', 'GitHub commit URL must contain an exact 40-character commit SHA.');
+    }
+    if (kind === 'tree') {
+      if (exactGithubCommit(parts[3])) return snapshotQualification(repository, parts[3], target, 'github-tree-url-exact-commit');
+      if (parts.length !== 4) return snapshotFailure('github.snapshot.tree-ref.ambiguous', 'Tree URL ref is ambiguous with a repository path. Paste the ref directly or use an exact commit URL.');
+      return snapshotQualification(repository, parts[3], target, 'github-tree-url-ref');
+    }
+    return snapshotFailure('github.snapshot.target.unsupported', 'Use a GitHub commit or tree URL.');
+  }
+
+  if (/\s/.test(target) || target.includes('://')) return snapshotFailure('github.snapshot.ref.invalid', 'Git ref must be an explicit branch, tag, or commit without whitespace.');
+  return snapshotQualification(configured.repo, target, target, 'explicit-ref');
+}
+
+export async function resolveGithubSnapshotInput(source = {}, input = '', options = {}) {
+  const qualified = qualifyGithubSnapshotInput(source, input);
+  if (!qualified.ok) return qualified;
+  const exact = exactGithubCommit(qualified.requestedRef);
+  if (exact) return Object.assign({}, qualified, { materializedCommit: exact.toLowerCase(), resolvedRef: exact.toLowerCase(), resolvedBy: qualified.resolvedBy });
+  try {
+    const resolved = await resolveGithubMaterializedCommit(source, qualified.requestedRef, options);
+    const commit = exactGithubCommit(resolved.commit);
+    if (!commit) return snapshotFailure('github.snapshot.commit.unavailable', 'Git ref did not resolve to an exact immutable commit.');
+    return Object.assign({}, qualified, {
+      materializedCommit: commit.toLowerCase(),
+      resolvedRef: String(resolved.ref || qualified.requestedRef).trim(),
+      resolvedBy: resolved.commitResolvedBy || resolved.resolvedBy || 'github.commit-resolution'
+    });
+  } catch (error) {
+    const failure = snapshotFailure('github.snapshot.resolution.failed', error?.message || 'GitHub snapshot resolution failed.');
+    failure.status = error?.status || null;
+    return failure;
+  }
+}
+
+function snapshotQualification(repository, requestedRef, inputTarget, resolvedBy) {
+  return { ok: true, schema: 'tiinex.github.snapshotInput.v1', repository, requestedRef: String(requestedRef || '').trim(), inputTarget: String(inputTarget || '').trim(), resolvedBy };
+}
+
+function snapshotFailure(code, message) {
+  return { ok: false, schema: 'tiinex.github.snapshotInput.v1', code, message };
+}