@tiinex/app 0.1.1

package/src/adapters/github/github.issueSnapshot.js

@@ -0,0 +1,475 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { createGithubEmbeddedArtifactRecord, extractEmbeddedTiinexMarkdownBlocks, githubIssueSyntheticFolder, sourceArtifactPathFromPublicationBody } from './github.issueEmbedded.js';
+import { parseExactGithubIssueTarget } from '@tiinex/core/sources/github/github.issueTarget.js';
+import { fetchGithubJson } from './github.readTransport.js';
+
+export const GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID = 'tiinex.github.issueSnapshot.v1';
+export const DEFAULT_ISSUE_SNAPSHOT_MAX_COMMENTS = 24;
+const TARGET_PATTERN = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/(issues|pull|discussions)\/(\d+)(?:[#?].*)?$/i;
+const HOSTED_DIRECT_ISSUE_PATTERN = /^https:\/\/[^/]+\/.*?issues\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)\/issue\.(md|json)(?:[#?].*)?$/i;
+
+export function parseGithubIssueSnapshotTarget(value = '') {
+  const raw = String(value || '').trim();
+  const hosted = raw.match(HOSTED_DIRECT_ISSUE_PATTERN);
+  if (hosted) {
+    const [, owner, repo, number, format] = hosted;
+    return {
+      ok: true,
+      schema: GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID,
+      input: raw,
+      owner,
+      repo,
+      repository: `${owner}/${repo}`,
+      kind: 'issue',
+      number: Number(number),
+      canonicalUrl: `https://github.com/${owner}/${repo}/issues/${number}`,
+      apiUrl: apiUrlFor({ owner, repo, kind: 'issue', number }),
+      directRawUrl: raw,
+      directRawFormat: String(format || '').toLowerCase()
+    };
+  }
+  const match = raw.match(TARGET_PATTERN);
+  if (!match) return { ok: false, input: raw, error: 'unsupported-github-issue-target' };
+  const [, owner, repo, kind, number] = match;
+  const normalizedKind = kind === 'pull' ? 'pull' : kind === 'discussions' ? 'discussion' : 'issue';
+  const sharedIssue = normalizedKind === 'issue' ? parseExactGithubIssueTarget(raw) : null;
+  const commentId = normalizedKind === 'issue' && sharedIssue?.ok ? sharedIssue.commentId : githubIssueCommentIdFromTarget(raw);
+  return {
+    ok: true,
+    schema: GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID,
+    input: raw,
+    owner,
+    repo,
+    repository: `${owner}/${repo}`,
+    kind: normalizedKind,
+    number: Number(number),
+    commentId,
+    canonicalUrl: normalizedKind === 'issue' && sharedIssue?.ok ? sharedIssue.inputTarget : `https://github.com/${owner}/${repo}/${kind}/${number}${commentId ? `#issuecomment-${commentId}` : ''}`,
+    issueCanonicalUrl: normalizedKind === 'issue' && sharedIssue?.ok ? sharedIssue.issueTarget : `https://github.com/${owner}/${repo}/${kind}/${number}`,
+    apiUrl: apiUrlFor({ owner, repo, kind: normalizedKind, number })
+  };
+}
+
+export function parseGithubIssueSnapshotTargets(value = '') {
+  const lines = Array.isArray(value) ? value : String(value || '').split(/\r?\n|,/);
+  const targets = [];
+  const errors = [];
+  const seen = new Set();
+  for (const line of lines) {
+    const text = String(line || '').trim();
+    if (!text) continue;
+    const parsed = parseGithubIssueSnapshotTarget(text);
+    if (!parsed.ok) {
+      errors.push({ ref: text, error: parsed.error });
+      continue;
+    }
+    const key = parsed.canonicalUrl.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(parsed);
+  }
+  return { schema: 'tiinex.github.issueSnapshot.targets.v1', targets, errors, counts: { targets: targets.length, errors: errors.length } };
+}
+
+export async function discoverGithubIssueSnapshotTargets(source = {}, options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  const repository = String(source.repo || source.repository || '').trim();
+  const [owner, repo] = repository.split('/').filter(Boolean);
+  const maxIssues = Math.max(1, Math.min(100, Number(options.maxIssues || options.maxIssueSnapshots || 12)));
+  if (!fetchImpl || !owner || !repo) {
+    return {
+      schema: 'tiinex.github.issueSnapshot.discovery.v1',
+      status: 'unavailable',
+      targets: [],
+      warnings: [finding('warning', 'github.issue.discovery.unavailable', 'GitHub issue discovery is unavailable without a fetch implementation and explicit repository boundary.', { surface: 'issueSnapshots' })],
+      errors: [],
+      counts: { discovered: 0, targets: 0, warnings: 1, errors: 0 }
+    };
+  }
+  const url = `https://api.github.com/repos/${owner}/${repo}/issues?state=all&sort=updated&direction=desc&per_page=${encodeURIComponent(String(maxIssues))}`;
+  try {
+    const rows = await fetchGithubJson(url, fetchImpl);
+    const seen = new Set();
+    const targets = [];
+    for (const row of Array.isArray(rows) ? rows : []) {
+      if (row && row.pull_request) continue;
+      const html = row.html_url || `https://github.com/${owner}/${repo}/issues/${row.number}`;
+      const parsed = parseGithubIssueSnapshotTarget(html);
+      if (!parsed.ok) continue;
+      const key = parsed.canonicalUrl.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      targets.push(Object.assign(parsed, { issue: row }));
+      if (targets.length >= maxIssues) break;
+    }
+    const warnings = [];
+    if (Array.isArray(rows) && rows.length >= maxIssues) warnings.push(finding('info', 'github.issue.discovery.bounded', `Issue discovery loaded a bounded first page of ${targets.length} issue target(s).`, { surface: 'issueSnapshots', maxIssues }));
+    return {
+      schema: 'tiinex.github.issueSnapshot.discovery.v1',
+      status: 'ready',
+      targets,
+      warnings,
+      errors: [],
+      counts: { discovered: targets.length, targets: targets.length, warnings: warnings.length, errors: 0 },
+      url
+    };
+  } catch (error) {
+    const warning = githubIssueFetchWarning(error, 'github.issue.discovery.unavailable', 'GitHub issue discovery is unavailable right now. Source boundary remains registered; retry later or provide explicit issue URLs.');
+    return { schema: 'tiinex.github.issueSnapshot.discovery.v1', status: 'unavailable', targets: [], warnings: [warning], errors: [], counts: { discovered: 0, targets: 0, warnings: 1, errors: 0 }, url };
+  }
+}
+
+export async function materializeGithubIssueSnapshots(issueUrlsOrTargets = '', options = {}) {
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  const parsed = Array.isArray(issueUrlsOrTargets)
+    ? { targets: issueUrlsOrTargets, errors: [], counts: { targets: issueUrlsOrTargets.length, errors: 0 } }
+    : parseGithubIssueSnapshotTargets(issueUrlsOrTargets);
+  const records = [];
+  const warnings = [];
+  const errors = [...parsed.errors];
+  const targetResults = [];
+  if (!fetchImpl) {
+    if (parsed.counts.targets) warnings.push(finding('warning', 'github.issue.reader.unavailable', 'Issue snapshot targets were parsed, but no fetch implementation is available.', { surface: 'issueSnapshots', targetCount: parsed.counts.targets }));
+    return { schema: 'tiinex.github.issueSnapshot.materialization.v1', records, warnings, errors, targetResults, counts: issueMaterializationCounts(parsed.counts.targets, records.length, warnings.length, errors.length, targetResults) };
+  }
+  const maxComments = Math.max(0, Math.min(100, Number(options.maxComments ?? DEFAULT_ISSUE_SNAPSHOT_MAX_COMMENTS)));
+  for (const target of parsed.targets) {
+    await yieldToBrowserIfAvailable();
+    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(issueTargetResult(target, { status: 'failed', warningCode: 'invalid-issue-target', message: normalized.error || 'invalid issue target' }));
+      continue;
+    }
+    if (normalized.kind === 'discussion') {
+      const warning = finding('warning', 'github.discussion.reader.deferred', 'GitHub Discussion snapshots are not available through the browser REST reader yet; this target remains deferred.', { surface: 'issueSnapshots', url: normalized.canonicalUrl });
+      warnings.push(warning);
+      targetResults.push(issueTargetResult(normalized, { status: 'deferred', warningCode: warning.code, records: 0 }));
+      continue;
+    }
+    try {
+      const issue = target.issue || await fetchGithubJson(normalized.apiUrl, fetchImpl);
+      const commentResult = normalized.commentId
+        ? await fetchSingleCommentForIssue(normalized, fetchImpl)
+        : maxComments && Number(issue.comments || 0) > 0
+          ? await fetchCommentsForIssue(normalized, fetchImpl, maxComments)
+          : { comments: [], warnings: [] };
+      warnings.push(...commentResult.warnings);
+      const issueRecords = createGithubIssueSnapshotRecords(Object.assign({}, issue, { target: normalized, comments: commentResult.comments, method: 'github-browser-issue-reader' }), 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: issue.transportTier || '',
+          loaded: true
+        }, record.sourceTarget || {});
+        records.push(record);
+      }
+      targetResults.push(issueTargetResult(normalized, { status: 'loaded', records: issueRecords.length, transportTier: issue.transportTier || '' }));
+    } catch (error) {
+      const warning = githubIssueFetchWarning(error, 'github.issue.snapshot.fetch-failed', `Could not fetch ${normalized.canonicalUrl}; snapshot remains unavailable.`, { url: normalized.canonicalUrl });
+      warnings.push(warning);
+      targetResults.push(issueTargetResult(normalized, { status: 'failed', warningCode: warning.code, message: warning.message, records: 0 }));
+    }
+  }
+  return {
+    schema: 'tiinex.github.issueSnapshot.materialization.v1',
+    records,
+    warnings,
+    errors,
+    targetResults,
+    counts: issueMaterializationCounts(parsed.counts.targets, records.length, warnings.length, errors.length, targetResults)
+  };
+}
+
+export function createGithubIssueSnapshotRecord(snapshot = {}, options = {}) {
+  return createGithubIssueSnapshotRecords(snapshot, options)[0];
+}
+
+export function createGithubIssueSnapshotRecords(snapshot = {}, options = {}) {
+  const target = snapshot.target || parseGithubIssueSnapshotTarget(snapshot.url || snapshot.html_url || '');
+  if (!target.ok) throw new Error(target.error || 'invalid issue snapshot target');
+  const issueEmbedded = extractEmbeddedTiinexMarkdownBlocks(snapshot.body || '');
+  const records = [];
+  if (issueEmbedded.length) {
+    const issueSourcePath = issueEmbedded.length === 1 ? sourceArtifactPathFromPublicationBody(snapshot.body || '') : '';
+    issueEmbedded.forEach((embedded, index) => {
+      records.push(createGithubEmbeddedArtifactRecord(embedded, { target, item: snapshot, ordinal: index, sourceKind: 'issue', sourceUrl: target.canonicalUrl, sourceArtifactPath: issueSourcePath, sourceUpdatedAt: issueSnapshotSortAt(snapshot), method: snapshot.method || 'github-explicit-snapshot-fixture', snapshotSchema: GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID }, options));
+    });
+  } else {
+    records.push(createGithubIssueSnapshotEvidenceRecord(snapshot, options));
+  }
+  const comments = Array.isArray(snapshot.comments) ? snapshot.comments : [];
+  let commentOrdinal = 0;
+  comments.forEach((comment, index) => {
+    const commentEmbedded = extractEmbeddedTiinexMarkdownBlocks(comment.body || '');
+    const commentSourcePath = commentEmbedded.length === 1 ? sourceArtifactPathFromPublicationBody(comment.body || '') : '';
+    commentEmbedded.forEach((embedded) => {
+      commentOrdinal += 1;
+      records.push(createGithubEmbeddedArtifactRecord(embedded, { target, item: comment, ordinal: commentOrdinal, sourceKind: 'comment', sourceUrl: comment.html_url || `${target.canonicalUrl}#issuecomment-${comment.id || index + 1}`, sourceArtifactPath: commentSourcePath, threadUpdatedAt: issueSnapshotSortAt(snapshot), method: snapshot.method || 'github-explicit-snapshot-fixture', snapshotSchema: GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID }, options));
+    });
+  });
+  return records;
+}
+
+function createGithubIssueSnapshotEvidenceRecord(snapshot = {}, options = {}) {
+  const target = snapshot.target || parseGithubIssueSnapshotTarget(snapshot.url || snapshot.html_url || '');
+  if (!target.ok) throw new Error(target.error || 'invalid issue snapshot target');
+  const comments = Array.isArray(snapshot.comments) ? snapshot.comments : [];
+  const createdAt = snapshot.created_at || snapshot.createdAt || options.createdAt || 'unknown';
+  const title = snapshot.title || `${capitalize(target.kind)} #${target.number}`;
+  const state = snapshot.state || 'unknown';
+  const author = snapshot.user?.login || snapshot.author || 'unknown';
+  const body = String(snapshot.body || '');
+  const method = snapshot.method || 'github-explicit-snapshot-fixture';
+  const sourceSortAt = issueSnapshotSortAt(snapshot);
+  const summary = issueSnapshotSummary({ body, title, target });
+  const markdown = [
+    '# Continuity Context',
+    '',
+    '- Envelope Schema: [tiinex.root.v1](tiinex.root.v1.schema.md)',
+    '- Current',
+    '  - Current Schema: [tiinex.evidence.v1](tiinex.evidence.v1.schema.md)',
+    `  - Created At: ${createdAt}`,
+    `  - Summary: ${summary}`,
+    '  - Status: source-backed/snapshot',
+    '  - Why: Captured as a read-only GitHub issue snapshot. It preserves observed source material without promoting it to project truth.',
+    '',
+    '---',
+    '',
+    `# ${title}`,
+    '',
+    '## Supported Claim Or Question',
+    '',
+    `This record preserves the observed GitHub ${target.kind} material for ${target.repository} #${target.number} so it can be inspected, searched, exported, and used explicitly by later Tiinex work.`,
+    '',
+    '## Provenance',
+    '',
+    `- Repository: ${target.repository}`,
+    `- Kind: ${target.kind}`,
+    `- Number: ${target.number}`,
+    `- URL: ${target.canonicalUrl}`,
+    `- State: ${state}`,
+    `- Author: ${author}`,
+    `- Transport: ${method}`,
+    '- Source Boundary: read-only GitHub issue snapshot; no repo-file discovery or remote mutation is implied.',
+    '',
+    '## Evidence Material',
+    '',
+    body ? markdownFence(body, 'md') : '_No issue body was captured._',
+    '',
+    comments.length ? '### Captured comments' : '',
+    ...comments.flatMap((comment, index) => [
+      comments.length ? `#### Comment ${index + 1} · ${comment.user?.login || comment.author || 'unknown'}` : '',
+      comments.length ? '' : '',
+      comments.length ? markdownFence(comment.body || '_No comment body captured._', 'md') : '',
+      comments.length ? '' : ''
+    ]),
+    '',
+    '## Preservation And Fidelity',
+    '',
+    '- Snapshot Type: GitHub issue materialization',
+    `- Snapshot Method: ${method}`,
+    `- Snapshot Target: ${target.canonicalUrl}`,
+    '- Fidelity: preserves title, state, author, body, and bounded comments available to the browser reader at materialization time.',
+    '',
+    '## Interpretation Limits',
+    '',
+    '- GitHub issues and comments are mutable source material.',
+    '- This Evidence record does not mean acceptance, task status, owner intent, or canonical Tiinex lineage by itself.',
+    '- Use a later explicit transition or artifact draft to interpret this source material.',
+    '',
+    '# Continuity Integrity',
+    '',
+    '- Snapshot Integrity',
+    `  - Method: ${method}`,
+    `  - Value: ${target.canonicalUrl}`
+  ].filter(Boolean).join('\n');
+  const record = createRecordFromMarkdown(markdown, { path: `${githubIssueSyntheticFolder(target)}/000-${slugPart(title || 'issue-snapshot')}.trace.md`, name: title, sourceMode: 'github-issue-snapshot' });
+  return Object.assign({}, record, {
+    sourceTarget: {
+      schema: 'tiinex.source.material.target.v1',
+      surface: 'issueSnapshots',
+      targetKind: `github-${target.kind || 'issue'}-snapshot`,
+      inputTarget: target.canonicalUrl,
+      sourceUpdatedAt: sourceSortAt,
+      sourceSortAt,
+      loaded: true
+    },
+    snapshot: {
+      schema: GITHUB_ISSUE_SNAPSHOT_SCHEMA_ID,
+      target,
+      comments: comments.length,
+      state,
+      author,
+      method,
+      sourceUpdatedAt: sourceSortAt,
+      sourceSortAt
+    }
+  });
+}
+
+function issueSnapshotSortAt(snapshot = {}) {
+  return String(snapshot.updated_at || snapshot.updatedAt || snapshot.created_at || snapshot.createdAt || '').trim();
+}
+
+export function materializeGithubIssueSnapshotFixtures(issueUrls = '', fixtures = {}) {
+  const parsed = parseGithubIssueSnapshotTargets(issueUrls);
+  const records = [];
+  const warnings = [];
+  const errors = [...parsed.errors];
+  for (const target of parsed.targets) {
+    const fixture = fixtures[target.canonicalUrl] || fixtures[`${target.repository}#${target.number}`] || fixtures[String(target.number)] || null;
+    if (!fixture) {
+      warnings.push({ code: 'github.issue.snapshot.fixture-missing', severity: 'warning', message: `No fixture supplied for ${target.canonicalUrl}; snapshot remains deferred.`, url: target.canonicalUrl });
+      continue;
+    }
+    try {
+      records.push(...createGithubIssueSnapshotRecords(Object.assign({}, fixture, { target })));
+    } catch (error) {
+      errors.push({ ref: target.canonicalUrl, error: error?.message || String(error) });
+    }
+  }
+  return {
+    schema: 'tiinex.github.issueSnapshot.materialization.v1',
+    records,
+    warnings,
+    errors,
+    counts: { targets: parsed.targets.length, records: records.length, warnings: warnings.length, errors: errors.length }
+  };
+}
+
+
+
+
+function issueTargetResult(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 || {});
+}
+
+function issueMaterializationCounts(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 issueSnapshotSummary({ body = '', title = '', target = {} } = {}) {
+  const excerpt = plainExcerpt(body, 140);
+  if (excerpt) return excerpt;
+  return `GitHub ${target.kind || 'issue'} snapshot for ${target.repository || 'repository'} #${target.number || ''}: ${plainExcerpt(title, 96) || 'untitled'}`.trim();
+}
+
+
+function plainExcerpt(value = '', limit = 140) {
+  return String(value || '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/!?\[[^\]]*\]\([^)]*\)/g, (match) => {
+      const label = match.match(/!?\[([^\]]*)\]/)?.[1] || '';
+      return label ? ` ${label} ` : ' ';
+    })
+    .replace(/[#>*_`~\-|:[\](){}]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, limit);
+}
+
+function markdownFence(text, lang = '') {
+  const body = String(text || '');
+  let fence = '```';
+  while (body.includes(fence)) fence += '`';
+  return `${fence}${lang ? lang : ''}\n${body}\n${fence}`;
+}
+
+async function fetchSingleCommentForIssue(target = {}, fetchImpl) {
+  const commentId = String(target.commentId || '').trim();
+  const commentUrl = `https://api.github.com/repos/${target.owner}/${target.repo}/issues/comments/${encodeURIComponent(commentId)}`;
+  try {
+    const comment = await fetchGithubJson(commentUrl, fetchImpl);
+    return { comments: comment && typeof comment === 'object' ? [comment] : [], warnings: [] };
+  } catch (error) {
+    return {
+      comments: [],
+      warnings: [githubIssueFetchWarning(error, 'github.issue.comment.fetch-failed', `Could not fetch issue comment ${commentId} for ${target.issueCanonicalUrl || target.canonicalUrl}; issue body still loaded without that comment.`, { url: commentUrl, targetUrl: target.canonicalUrl, commentId })]
+    };
+  }
+}
+
+async function fetchCommentsForIssue(target = {}, fetchImpl, maxComments = 20) {
+  const commentsUrl = `https://api.github.com/repos/${target.owner}/${target.repo}/issues/${target.number}/comments?per_page=${encodeURIComponent(String(maxComments))}`;
+  try {
+    const comments = await fetchGithubJson(commentsUrl, fetchImpl);
+    return { comments: Array.isArray(comments) ? comments.slice(0, maxComments) : [], warnings: [] };
+  } catch (error) {
+    return {
+      comments: [],
+      warnings: [githubIssueFetchWarning(error, 'github.issue.comments.fetch-failed', `Could not fetch comments for ${target.issueCanonicalUrl || target.canonicalUrl}; issue body still loaded without comments.`, { url: commentsUrl, targetUrl: target.canonicalUrl })]
+    };
+  }
+}
+
+
+export function githubIssueFetchWarning(error, code = 'github.issue.fetch-failed', message = '', extra = {}) {
+  return finding('warning', code, message || 'GitHub issue reader could not fetch the requested issue material.', Object.assign({ surface: 'issueSnapshots', status: error?.status || 0, url: error?.url || '' }, extra));
+}
+
+function githubIssueCommentIdFromTarget(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    return url.hash.match(/issuecomment-(\d+)/i)?.[1] || '';
+  } catch (_) {}
+  return raw.match(/issuecomment-(\d+)/i)?.[1] || '';
+}
+
+function apiUrlFor({ owner, repo, kind, number }) {
+  if (kind === 'discussion') return `https://api.github.com/repos/${owner}/${repo}/discussions/${number}`;
+  if (kind === 'pull') return `https://api.github.com/repos/${owner}/${repo}/pulls/${number}`;
+  return `https://api.github.com/repos/${owner}/${repo}/issues/${number}`;
+}
+function finding(severity, code, message, extra = {}) { return Object.assign({ severity, code, message }, extra); }
+function capitalize(value = '') { const text = String(value || 'item'); return text.charAt(0).toUpperCase() + text.slice(1); }
+
+
+function yieldToBrowserIfAvailable() {
+  if (typeof window === 'undefined') return Promise.resolve();
+  return new Promise((resolve) => {
+    if (typeof window.requestIdleCallback === 'function') {
+      window.requestIdleCallback(() => resolve(), { timeout: 80 });
+      return;
+    }
+    if (typeof window.requestAnimationFrame === 'function') {
+      window.requestAnimationFrame(() => resolve());
+      return;
+    }
+    window.setTimeout(resolve, 0);
+  });
+}
+
+export function __testYieldToBrowserIfAvailable() {
+  return yieldToBrowserIfAvailable();
+}
+
+function slugPart(value = '') { return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item'; }

package/src/adapters/github/github.issueSurface.js

@@ -0,0 +1,188 @@
+import { authorizeSourceTransport } from '../../sources/transport.policy.js';
+import { buildGithubTransportPlan, normalizeGithubTransportTier } from '../../sources/github/github.transport.js';
+import { DEFAULT_ISSUE_SNAPSHOT_MAX_COMMENTS, discoverGithubIssueSnapshotTargets, materializeGithubIssueSnapshotFixtures, materializeGithubIssueSnapshots, parseGithubIssueSnapshotTargets } from './github.issueSnapshot.js';
+import { discoverGithubIssueSnapshotTargetsViaHostedMirror, materializeGithubIssueSnapshotsViaHostedMirror } from './github.issueMirror.js';
+import { directIssueDiscoveryUnavailable, issueApiFetchForTier, issueDirectFetchForTier, issueMirrorFetchForTier, materializeDirectIssueTargets } from './github.issueTransport.js';
+
+const ISSUE_TRANSPORT_FALLBACKS = Object.freeze({
+  default: Object.freeze(['cache', 'mirror', 'proxy', 'direct']),
+  cache: Object.freeze(['cache', 'mirror', 'proxy', 'direct']),
+  mirror: Object.freeze(['mirror', 'proxy', 'direct']),
+  proxy: Object.freeze(['proxy']),
+  direct: Object.freeze(['direct'])
+});
+
+export async function materializeGithubIssueSurface(source = {}, input = {}, options = {}) {
+  const adapterId = options.adapterId || 'github';
+  const sourceId = source?.id || '';
+  const fetchImpl = options.fetchImpl;
+  const policyInput = options.transportPolicy || null;
+  const warnings = [];
+  const errors = [];
+  const diagnostics = { transportEvents: [] };
+  const requestedTier = requestedIssueTransportTier(options);
+  const issueTiers = issueTransportFallbackTiers(requestedTier, options);
+  const sourceFetchImpl = options.sourceFetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  const surface = { attempted: true, requested: true, requestedCount: 0, discovered: 0, loaded: 0, failed: 0, records: [] };
+  let result = { records: [], warnings: [], errors: [], counts: { targets: 0, records: 0, warnings: 0, errors: 0 } };
+  const explicitParsed = parseGithubIssueSnapshotTargets(input.issueUrls || []);
+  let parsed = explicitParsed;
+  progress(options, { phase: 'issue-snapshots', percent: 32, label: input.issueDiscovery ? 'Discovering bounded GitHub issue snapshots' : 'Loading explicit GitHub issue targets' });
+
+  if (input.issueDiscovery) {
+    const auth = policyInput ? authorizeSourceTransport({ kind: 'github.issue-discovery', sourceId, adapterId, requestedRequests: Number(options.maxIssues || 25) + 1 }, policyInput) : null;
+    if (auth && !auth.allowed) {
+      diagnostics.transportPolicy = auth;
+      Object.assign(surface, explicitParsed.counts.targets ? { discoveryUnavailable: true } : { skipped: true, unavailable: true });
+      for (const issue of auth.findings || []) {
+        const warning = { code: issue.code, severity: issue.severity || 'warning', surface: 'issueSnapshots', message: issue.message, sourceId, adapterId, retryable: issue.retryable === true };
+        warnings.push(warning);
+        diagnostics.transportEvents.push(Object.assign({ resultKind: 'issue-discovery-policy' }, warning));
+      }
+    } else {
+      const discovered = await discoverIssueTargetsForTiers(source, Object.assign({}, options, { fetchImpl, sourceFetchImpl }), issueTiers, diagnostics);
+      warnings.push(...(discovered.warnings || []).map((warning) => Object.assign({ surface: 'issueSnapshots' }, warning)));
+      errors.push(...(discovered.errors || []).map((error) => Object.assign({ surface: 'issueSnapshots' }, error)));
+      const unionTargets = uniqueIssueTargets((discovered.targets || []).concat(explicitParsed.targets || []));
+      parsed = { targets: unionTargets, errors: explicitParsed.errors || [], counts: { targets: unionTargets.length, errors: Number(explicitParsed.counts?.errors || 0) } };
+      diagnostics.issueSnapshotDiscovery = { status: discovered.status, url: discovered.url || '', discovered: discovered.counts?.discovered || 0, explicitTargets: Number(explicitParsed.counts?.targets || 0), unionTargets: unionTargets.length, transportTier: discovered.transportTier || '' };
+      surface.discovered = Number(discovered.counts?.discovered || 0);
+    }
+  }
+
+  diagnostics.issueSnapshotTargets = parsed.counts.targets;
+  Object.assign(surface, { requestedCount: parsed.counts.targets, targets: parsed.counts.targets });
+  if (parsed.errors.length) errors.push(...parsed.errors.map((entry) => Object.assign({ surface: 'issueSnapshots', ref: entry.ref }, entry)));
+
+  const maxComments = Math.max(0, Math.min(100, Number(options.maxComments ?? DEFAULT_ISSUE_SNAPSHOT_MAX_COMMENTS)));
+  const materializationAuth = policyInput && parsed.counts.targets && !surface.skipped
+    ? authorizeSourceTransport({ kind: 'github.issue-snapshot-load', sourceId, adapterId, requestedRequests: Number(parsed.counts.targets || 0) * (maxComments > 0 ? 2 : 1) }, policyInput)
+    : null;
+  if (materializationAuth && !materializationAuth.allowed) {
+    diagnostics.transportPolicy = materializationAuth;
+    Object.assign(surface, { skipped: true, unavailable: true });
+    for (const issue of materializationAuth.findings || []) {
+      const warning = { code: issue.code, severity: issue.severity || 'warning', surface: 'issueSnapshots', message: issue.message, sourceId, adapterId, retryable: issue.retryable === true };
+      warnings.push(warning);
+      diagnostics.transportEvents.push(Object.assign({ resultKind: 'issue-snapshot-load-policy' }, warning));
+    }
+  } else if (options.issueSnapshotFixtures && parsed.counts.targets && input.issueUrls && !input.issueDiscovery) result = materializeGithubIssueSnapshotFixtures(input.issueUrls || [], options.issueSnapshotFixtures);
+  else if (parsed.counts.targets) result = await materializeIssueTargetsForTiers(parsed.targets, source, Object.assign({}, options, { fetchImpl, sourceFetchImpl, maxComments }), issueTiers, diagnostics);
+  else if (!surface.skipped) {
+    warnings.push({ code: 'github.issue.discovery.no-targets', severity: 'warning', surface: 'issueSnapshots', requested: true, attempted: true, unavailable: true, targetCount: 0, message: 'Issue snapshot discovery was selected, but no issue targets were discovered or provided.' });
+    Object.assign(surface, { unavailable: true, skipped: true });
+  }
+
+  warnings.push(...(result.warnings || []).map((warning) => Object.assign({ surface: 'issueSnapshots' }, warning)));
+  errors.push(...(result.errors || []).map((error) => Object.assign({ surface: 'issueSnapshots' }, error)));
+  diagnostics.issueSnapshotRecords = result.records.length;
+  diagnostics.issueSnapshotTargetResults = Array.isArray(result.targetResults) ? result.targetResults : [];
+  diagnostics.issueSnapshotMaterialization = {
+    targets: Number(result.counts?.targets || 0),
+    records: Number(result.records?.length || 0),
+    loadedTargets: Number(result.counts?.loadedTargets || 0),
+    failedTargets: Number(result.counts?.failedTargets || 0),
+    deferredTargets: Number(result.counts?.deferredTargets || 0),
+    warnings: Number(result.counts?.warnings || 0),
+    errors: Number(result.counts?.errors || 0)
+  };
+  Object.assign(surface, {
+    loaded: result.records.length,
+    loadedTargets: Number(result.counts?.loadedTargets || 0),
+    failed: Number(result.counts?.failedTargets ?? Math.max(0, Number(result.counts?.targets || 0) - Number(result.records.length || 0))),
+    deferred: Number(result.counts?.deferredTargets || 0),
+    records: result.records.map((record) => record.id).filter(Boolean),
+    transportTier: result.transportTier || '',
+    attemptedTiers: issueTiers.slice()
+  });
+  if (!result.records.length && parsed.counts.targets && !surface.skipped) surface.unavailable = true;
+  for (const record of result.records || []) record.sourceTarget = Object.assign({ schema: 'tiinex.source.material.target.v1', surface: 'issueSnapshots', targetKind: 'github-issue-snapshot', loaded: true }, record.sourceTarget || {});
+  return { records: result.records || [], warnings, errors, diagnostics, surface, counts: result.counts || {} };
+}
+
+
+
+function uniqueIssueTargets(targets = []) {
+  const seen = new Set();
+  const out = [];
+  for (const target of Array.isArray(targets) ? targets : []) {
+    const key = String(target?.canonicalUrl || target?.issueCanonicalUrl || target?.input || '').trim().toLowerCase();
+    if (!key || seen.has(key)) continue;
+    seen.add(key); out.push(target);
+  }
+  return out;
+}
+
+function issueTransportFallbackTiers(tier = '', options = {}) {
+  const normalized = normalizeGithubTransportTier(tier);
+  const tiers = Array.from(normalized ? (ISSUE_TRANSPORT_FALLBACKS[normalized] || [normalized]) : ISSUE_TRANSPORT_FALLBACKS.default);
+  if (options.allowCache === false && normalized !== 'cache') return tiers.filter((candidate) => candidate !== 'cache');
+  return tiers;
+}
+
+async function discoverIssueTargetsForTiers(source = {}, options = {}, tiers = [''], diagnostics = {}) {
+  let last = null;
+  for (let index = 0; index < tiers.length; index += 1) {
+    const tier = tiers[index];
+    const discovered = tier === 'cache'
+      ? await discoverGithubIssueSnapshotTargetsViaHostedMirror(source, Object.assign({}, options, { fetchImpl: issueMirrorFetchForTier(source, tier, options.sourceFetchImpl, diagnostics), cacheMode: 'cache-only', transportTier: 'cache', onTransportEvent: pushIssueTransportEvent(diagnostics, source, tier) }))
+      : tier === 'mirror'
+        ? await discoverGithubIssueSnapshotTargetsViaHostedMirror(source, Object.assign({}, options, { fetchImpl: issueMirrorFetchForTier(source, tier, options.sourceFetchImpl, diagnostics), cacheMode: 'refresh', transportTier: 'mirror', onTransportEvent: pushIssueTransportEvent(diagnostics, source, tier) }))
+      : tier === 'proxy'
+        ? await discoverGithubIssueSnapshotTargets(source, Object.assign({}, options, { fetchImpl: issueApiFetchForTier(source, tier, options.sourceFetchImpl, diagnostics, options) }))
+        : directIssueDiscoveryUnavailable(source, diagnostics);
+    last = Object.assign({ transportTier: tier }, discovered || {});
+    if (Array.isArray(last.targets) && last.targets.length) return last;
+    if (last.status === 'ready' && tier !== 'mirror') return last;
+    const nextTier = tiers[index + 1] || '';
+    if (nextTier) emitIssueFallback(diagnostics, source, tier, nextTier, 'discovery');
+  }
+  return last || { schema: 'tiinex.github.issueSnapshot.discovery.v1', status: 'unavailable', targets: [], warnings: [], errors: [], counts: { discovered: 0, targets: 0, warnings: 0, errors: 0 }, transportTier: '' };
+}
+
+async function materializeIssueTargetsForTiers(targets = [], source = {}, options = {}, tiers = [''], diagnostics = {}) {
+  let last = null;
+  for (let index = 0; index < tiers.length; index += 1) {
+    const tier = tiers[index];
+    const result = tier === 'cache'
+      ? await materializeGithubIssueSnapshotsViaHostedMirror(targets, Object.assign({}, options, { fetchImpl: issueMirrorFetchForTier(source, tier, options.sourceFetchImpl, diagnostics), cacheMode: 'cache-only', transportTier: 'cache', onTransportEvent: pushIssueTransportEvent(diagnostics, source, tier) }))
+      : tier === 'mirror'
+        ? await materializeGithubIssueSnapshotsViaHostedMirror(targets, Object.assign({}, options, { fetchImpl: issueMirrorFetchForTier(source, tier, options.sourceFetchImpl, diagnostics), cacheMode: 'refresh', transportTier: 'mirror', onTransportEvent: pushIssueTransportEvent(diagnostics, source, tier) }))
+      : tier === 'proxy'
+        ? await materializeGithubIssueSnapshots(targets, Object.assign({}, options, { fetchImpl: issueApiFetchForTier(source, tier, options.sourceFetchImpl, diagnostics, options), maxComments: options.maxComments }))
+        : await materializeDirectIssueTargets(targets, source, Object.assign({}, options, { fetchImpl: issueDirectFetchForTier(source, options.sourceFetchImpl, diagnostics) }), diagnostics);
+    last = Object.assign({ transportTier: tier }, result || {});
+    if (Array.isArray(last.records) && last.records.length) return last;
+    const nextTier = tiers[index + 1] || '';
+    if (nextTier) emitIssueFallback(diagnostics, source, tier, nextTier, 'materialization');
+    else return last;
+  }
+  return last || { records: [], warnings: [], errors: [], counts: { targets: 0, records: 0, warnings: 0, errors: 0 }, targetResults: [] };
+}
+
+function emitIssueFallback(diagnostics = {}, source = {}, fromTier = '', toTier = '', phase = '') {
+  diagnostics.transportEvents?.push?.({
+    adapterId: 'github',
+    sourceId: source?.id || '',
+    repo: source?.repo || source?.repository || '',
+    tier: fromTier,
+    resource: 'api-json',
+    code: 'github.issue.transport.surface-fallback',
+    severity: 'info',
+    phase,
+    message: `Issue snapshots skipped ${fromTier} and tried ${toTier} because the selected transport did not materialize this surface.`
+  });
+}
+
+function requestedIssueTransportTier(options = {}) {
+  const fromOrder = options.transportOrderExact === true && Array.isArray(options.preferredTransports) ? options.preferredTransports[0] : '';
+  return normalizeGithubTransportTier(options.transportRefreshTier || options.transportPolicy?.requestedTier || fromOrder || '');
+}
+
+function pushIssueTransportEvent(diagnostics = {}, source = {}, tier = '') {
+  return (event = {}) => diagnostics.transportEvents?.push?.(Object.assign({ adapterId: 'github', sourceId: source?.id || '', repo: source?.repo || source?.repository || '', tier: tier || event.tier || '', resource: 'api-json' }, event));
+}
+
+function progress(options = {}, event = {}) {
+  if (typeof options.onProgress === 'function') options.onProgress(event);
+}