@tiinex/app 0.1.1

package/src/sources/github/github.transport.js

@@ -0,0 +1,472 @@
+const DEFAULT_ORDER = Object.freeze(['cache', 'mirror', 'proxy', 'direct']);
+export const GITHUB_TRANSPORT_TIER_ORDER = DEFAULT_ORDER;
+
+export function normalizeGithubTransportTier(value = '') {
+  const tier = String(value || '').trim().toLowerCase();
+  return DEFAULT_ORDER.includes(tier) ? tier : '';
+}
+
+export function nextGithubTransportTier(value = '', configured = {}) {
+  const tier = normalizeGithubTransportTier(value) || 'cache';
+  const index = DEFAULT_ORDER.indexOf(tier);
+  for (const candidate of DEFAULT_ORDER.slice(index + 1)) {
+    if (candidate === 'cache' || candidate === 'direct' || configured[candidate] !== false) return candidate;
+  }
+  return '';
+}
+
+export function githubTransportOrderFromTier(tier = '') {
+  const normalized = normalizeGithubTransportTier(tier);
+  return normalized ? [normalized] : Array.from(DEFAULT_ORDER);
+}
+export const SOURCE_CACHE_PREFIX = 'tiinex.source-cache.v1:';
+
+export function normalizeGithubRepoIdentity(repo = '') {
+  const value = String(repo || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '');
+  const parts = value.split('/').filter(Boolean);
+  if (parts.length < 2) return '';
+  return `${parts[0]}/${parts[1]}`.toLowerCase();
+}
+
+export function buildGithubTransportPlan(source = {}, options = {}) {
+  const repo = normalizeGithubRepoIdentity(source.repo || source.repository || options.repo || '');
+  const workspaceConfig = options.workspaceConfig || {};
+  const exactOrder = options.transportOrderExact === true;
+  const order = normalizeOrder(options.transportOrder || options.preferredTransports || DEFAULT_ORDER, { appendMissing: !exactOrder });
+  const mirrors = configuredMirrorsFor(repo, workspaceConfig, options);
+  const proxies = configuredProxiesFor(repo, workspaceConfig, options);
+  const requestedProxy = exactOrder && order.includes('proxy');
+  const autoProxy = proxies.some((proxy) => proxy.activation === 'auto');
+  const allow = {
+    cache: options.allowCache !== false,
+    mirror: options.allowMirror !== false,
+    proxy: options.allowProxy !== false && (autoProxy || requestedProxy || options.allowManualProxy === true),
+    direct: options.allowDirect !== false
+  };
+  const configured = {
+    cache: true,
+    mirror: Boolean(mirrors.length || options.mirrorFetchImpl || options.mirrorRawUrl || options.mirrorApiUrl),
+    proxy: Boolean(proxies.length || options.proxyFetchImpl || options.proxyRawUrl || options.proxyApiUrl),
+    direct: true
+  };
+  const tiers = order
+    .filter((tier) => allow[tier])
+    .concat(exactOrder || order.includes('direct') || !allow.direct ? [] : ['direct'])
+    .filter((tier, index, array) => array.indexOf(tier) === index);
+  return Object.freeze({
+    schema: 'tiinex.github.transport.plan.v1',
+    repo,
+    order: Object.freeze(order),
+    tiers: Object.freeze(tiers),
+    allow: Object.freeze(allow),
+    configured: Object.freeze(configured),
+    mirrors: Object.freeze(mirrors),
+    proxies: Object.freeze(proxies),
+    label: tiers.join(' → ') || 'unavailable',
+    boundary: 'GitHub source transport tries explicit configured/cache tiers in order. It must not infer source provenance or silently invent proxy/mirror transports.'
+  });
+}
+
+export function createGithubTransportFetch(source = {}, options = {}) {
+  const directFetch = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  const plan = options.transportPlan?.schema === 'tiinex.github.transport.plan.v1'
+    ? options.transportPlan
+    : buildGithubTransportPlan(source, options);
+  const events = [];
+  const cache = createSourceTextCache(options);
+
+  function emit(event) {
+    const enriched = Object.assign({ adapterId: 'github', sourceId: source?.id || '', repo: plan.repo || '' }, event);
+    events.push(enriched);
+    if (typeof options.onTransportEvent === 'function') options.onTransportEvent(enriched);
+  }
+
+  async function transportFetch(url, init = {}) {
+    const resource = classifyGithubResource(url, init);
+    const cacheKey = cacheKeyFor(url, resource);
+    for (const tier of plan.tiers) {
+      if (tier === 'cache') {
+        const cached = cache.get(cacheKey);
+        if (cached) {
+          emit({ tier, code: 'github.transport.cache.hit', severity: 'info', url, resource });
+          return makeResponse(cached.body, { url, tier, contentType: cached.contentType || contentTypeFor(resource) });
+        }
+        emit({ tier, code: 'github.transport.cache.miss', severity: 'info', url, resource });
+        continue;
+      }
+      if (tier === 'mirror') {
+        const res = await tryConfiguredTransport('mirror', url, init, resource, options, emit);
+        if (res) {
+          await cache.put(cacheKey, await responseBodyText(res, resource), contentTypeFor(resource));
+          return makeResponse(cache.get(cacheKey)?.body || '', { url, tier, contentType: contentTypeFor(resource), status: res.status || 200, statusText: res.statusText || 'OK' });
+        }
+        continue;
+      }
+      if (tier === 'proxy') {
+        const res = await tryConfiguredTransport('proxy', url, init, resource, options, emit);
+        if (res) {
+          await cache.put(cacheKey, await responseBodyText(res, resource), contentTypeFor(resource));
+          return makeResponse(cache.get(cacheKey)?.body || '', { url, tier, contentType: contentTypeFor(resource), status: res.status || 200, statusText: res.statusText || 'OK' });
+        }
+        continue;
+      }
+      if (tier === 'direct') {
+        if (!directFetch) {
+          emit({ tier, code: 'github.transport.direct.unavailable', severity: 'warning', url, resource });
+          continue;
+        }
+        try {
+          emit({ tier, code: 'github.transport.direct.try', severity: 'info', url, resource });
+          const res = await directFetch(url, init);
+          if (res?.ok) {
+            emit({ tier, code: 'github.transport.direct.ok', severity: 'info', url, resource, status: res.status || 200 });
+            await cache.put(cacheKey, await responseBodyText(res, resource), contentTypeFor(resource));
+            return makeResponse(cache.get(cacheKey)?.body || '', { url, tier, contentType: contentTypeFor(resource), status: res.status || 200, statusText: res.statusText || 'OK' });
+          }
+          emit({ tier, code: 'github.transport.direct.failed', severity: 'warning', url, resource, status: res?.status || 0, message: res?.statusText || '' });
+          return res;
+        } catch (error) {
+          emit({ tier, code: 'github.transport.direct.exception', severity: 'warning', url, resource, message: messageOf(error) });
+        }
+      }
+    }
+    emit({ tier: 'none', code: 'github.transport.exhausted', severity: 'error', url, resource });
+    return makeResponse('', { ok: false, status: 503, statusText: 'Transport unavailable', url, tier: 'none', contentType: contentTypeFor(resource) });
+  }
+
+  return Object.freeze({ fetch: transportFetch, plan, events });
+}
+
+
+export function githubSourceCacheResourceForUrl(url = '', init = {}) {
+  return classifyGithubResource(url, init);
+}
+
+export function githubSourceCacheKeyForUrl(url = '', resource = '') {
+  return cacheKeyFor(url, resource || classifyGithubResource(url));
+}
+
+export function readGithubSourceCacheEntry(url = '', resource = '', options = {}) {
+  const key = cacheKeyFor(url, resource || classifyGithubResource(url));
+  const memory = options.sourceCache || moduleMemoryCache;
+  const storage = options.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  const mem = readObject(memory, key);
+  if (mem?.body != null) return Object.assign({ key, cache: 'memory' }, mem);
+  try {
+    const raw = storage?.getItem?.(key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed?.body != null) {
+      writeObject(memory, key, parsed);
+      return Object.assign({ key, cache: 'localStorage' }, parsed);
+    }
+  } catch (_) {}
+  return null;
+}
+
+export async function writeGithubSourceCacheEntry(url = '', body = '', contentType = '', resource = '', options = {}) {
+  const text = String(body || '');
+  if (!text) return false;
+  const maxChars = Math.max(0, Number(options.maxCacheEntryChars || 750000));
+  if (maxChars && text.length > maxChars) return false;
+  const key = cacheKeyFor(url, resource || classifyGithubResource(url));
+  const entry = { body: text, contentType: contentType || contentTypeFor(resource || classifyGithubResource(url)), cachedAt: new Date().toISOString() };
+  const memory = options.sourceCache || moduleMemoryCache;
+  const storage = options.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  writeObject(memory, key, entry);
+  try { storage?.setItem?.(key, JSON.stringify(entry)); } catch (_) {}
+  return true;
+}
+
+export function makeGithubSourceCacheResponse(body = '', options = {}) {
+  return makeResponse(String(body || ''), {
+    url: options.url || '',
+    tier: options.tier || 'cache',
+    status: options.status || 200,
+    statusText: options.statusText || 'OK',
+    contentType: options.contentType || contentTypeFor(options.resource || 'source-resource')
+  });
+}
+
+export function createGithubCacheOnlyFetch(options = {}) {
+  return async function githubCacheOnlyFetch(url, init = {}) {
+    const resource = options.resource || classifyGithubResource(url, init);
+    const cached = readGithubSourceCacheEntry(url, resource, options);
+    if (cached?.body != null) return makeResponse(cached.body, { url, tier: 'cache', contentType: cached.contentType || contentTypeFor(resource) });
+    return makeResponse('', { ok: false, status: 404, statusText: 'Source cache miss', url, tier: 'cache', contentType: contentTypeFor(resource) });
+  };
+}
+
+
+export function githubRawUrlForSourcePath(source = {}, path = '') {
+  const repo = normalizeGithubRepoIdentity(source.repo || source.repository || source.config?.repo || '');
+  const ref = String(source.ref || source.config?.ref || '').trim();
+  const cleanPath = String(path || '').trim().replace(/^\/+/, '').replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+  if (!repo || !ref || !cleanPath) return '';
+  const [owner, name] = repo.split('/');
+  return `https://raw.githubusercontent.com/${owner}/${name}/${ref}/${cleanPath}`;
+}
+
+export function readGithubCachedTextForSourcePath(source = {}, path = '', options = {}) {
+  const url = githubRawUrlForSourcePath(source, path);
+  if (!url) return null;
+  const key = cacheKeyFor(url, 'raw-markdown');
+  const memory = options.sourceCache || moduleMemoryCache;
+  const storage = options.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  const mem = readObject(memory, key);
+  if (mem?.body != null) return { body: String(mem.body || ''), contentType: mem.contentType || '', url, key, cache: 'memory' };
+  try {
+    const raw = storage?.getItem?.(key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed?.body != null) {
+      writeObject(memory, key, parsed);
+      return { body: String(parsed.body || ''), contentType: parsed.contentType || '', url, key, cache: 'localStorage' };
+    }
+  } catch (_) {}
+  return null;
+}
+
+export function hydrateGithubRecordFromSourceCache(record = {}, options = {}) {
+  if (String(record.markdown || '').trim()) return record;
+  const source = record.source || {};
+  const adapter = String(source.adapterId || record.sourceMode || '').toLowerCase();
+  if (!adapter.includes('github') && !String(record.sourceMode || '').toLowerCase().includes('source-backed')) return record;
+  const cached = readGithubCachedTextForSourcePath(source, record.path || record.name || '', options);
+  if (!cached?.body) return record;
+  return Object.assign({}, record, {
+    markdown: cached.body,
+    materialAvailability: 'available',
+    materialUnavailable: false,
+    cacheState: `source-text-cache-hydrated:${cached.cache || 'cache'}`
+  });
+}
+
+export function hydrateGithubWorkspaceFromSourceCache(workspace = {}, options = {}) {
+  if (!workspace || typeof workspace !== 'object') return workspace;
+  const records = Array.isArray(workspace.records) ? workspace.records : [];
+  if (!records.length) return workspace;
+  let changed = false;
+  const hydratedRecords = records.map((record) => {
+    const hydrated = hydrateGithubRecordFromSourceCache(record, options);
+    if (hydrated !== record) changed = true;
+    return hydrated;
+  });
+  return changed ? Object.assign({}, workspace, { records: hydratedRecords }) : workspace;
+}
+
+export function clearGithubSourceTextCacheForSource(source = {}, options = {}) {
+  const repo = normalizeGithubRepoIdentity(source.repo || source.repository || source.config?.repo || '');
+  if (!repo) return 0;
+  const [owner, name] = repo.split('/');
+  const needles = [
+    `raw.githubusercontent.com/${owner}/${name}/`,
+    `api.github.com/repos/${owner}/${name}/`,
+    `issues/github.com/${owner}/${name}`,
+    `mirrors/github.com/${owner}/${name}`,
+    `github-repo-discovery/${owner}/${name}`
+  ];
+  const matchesSource = (key = '') => {
+    const lower = String(key || '').toLowerCase();
+    return lower.startsWith(SOURCE_CACHE_PREFIX) && needles.some((needle) => lower.includes(String(needle || '').toLowerCase()));
+  };
+  const memory = options.sourceCache || moduleMemoryCache;
+  let removed = 0;
+  for (const key of Object.keys(memory || {})) {
+    if (matchesSource(key)) {
+      delete memory[key];
+      removed += 1;
+    }
+  }
+  const storage = options.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  try {
+    const keys = [];
+    for (let index = 0; index < (storage?.length || 0); index += 1) {
+      const key = storage.key(index);
+      if (key && matchesSource(key)) keys.push(key);
+    }
+    for (const key of keys) {
+      storage.removeItem(key);
+      removed += 1;
+    }
+  } catch (_) {}
+  return removed;
+}
+
+function normalizeOrder(input = DEFAULT_ORDER, options = {}) {
+  const appendMissing = options.appendMissing !== false;
+  const values = (Array.isArray(input) ? input : String(input || '').split(/[>,\s]+/))
+    .map((item) => normalizeGithubTransportTier(item))
+    .filter(Boolean);
+  const out = values.length ? values : Array.from(DEFAULT_ORDER);
+  if (appendMissing) for (const tier of DEFAULT_ORDER) if (!out.includes(tier)) out.push(tier);
+  return out;
+}
+
+function configuredMirrorsFor(repo, workspaceConfig = {}, options = {}) {
+  const matches = [];
+  const configured = Array.isArray(workspaceConfig.repositoryMirrors) ? workspaceConfig.repositoryMirrors : [];
+  for (const item of configured) {
+    const itemRepo = normalizeGithubRepoIdentity(item.repository || item.repo || item.url || '');
+    if (!repo || itemRepo !== repo) continue;
+    matches.push({ kind: 'snapshot', label: item.label || item.name || 'Source Pages mirror', repository: repo, metadataUrl: item.metadataUrl || item.metadata || '', url: item.url || '' });
+  }
+  if (options.mirrorRawUrl || options.mirrorApiUrl) matches.push({ kind: 'snapshot', label: options.mirrorLabel || 'Configured mirror', repository: repo, rawUrl: options.mirrorRawUrl || '', apiUrl: options.mirrorApiUrl || '' });
+  return matches;
+}
+
+function configuredProxiesFor(repo, workspaceConfig = {}, options = {}) {
+  const matches = [];
+  const configured = Array.isArray(workspaceConfig.repositoryTransports) ? workspaceConfig.repositoryTransports : [];
+  for (const item of configured) {
+    const kind = String(item.kind || '').toLowerCase();
+    if (!kind.includes('proxy')) continue;
+    const match = String(item.match || item.repository || item.repo || '').toLowerCase();
+    const proxy = String(item.proxy || item.proxyUrl || '').trim();
+    const activation = transportActivation(item);
+    if (!proxy || activation === 'disabled') continue;
+    const matchesRepo = !match || match === repo || match === 'github.com/*' || match === 'github.com/**' || match.endsWith('*');
+    if (matchesRepo) matches.push({ kind: 'git-proxy', label: item.label || item.name || 'Configured proxy', repository: repo, proxyUrl: proxy, activation });
+  }
+  if (options.proxyRawUrl || options.proxyApiUrl) matches.push({ kind: 'proxy', label: options.proxyLabel || 'Configured proxy', repository: repo, rawUrl: options.proxyRawUrl || '', apiUrl: options.proxyApiUrl || '', activation: 'auto' });
+  return matches;
+}
+
+function transportActivation(item = {}) {
+  const value = String(item.activation || item.mode || item.use || '').trim().toLowerCase();
+  if (['manual', 'explicit', 'opt-in', 'optin', 'user'].includes(value)) return 'manual';
+  if (['off', 'disabled', 'never'].includes(value)) return 'disabled';
+  return 'auto';
+}
+
+async function tryConfiguredTransport(tier, url, init, resource, options, emit) {
+  const fetcher = tier === 'mirror' ? options.mirrorFetchImpl : options.proxyFetchImpl;
+  const rawBase = tier === 'mirror' ? options.mirrorRawUrl : options.proxyRawUrl;
+  const apiBase = tier === 'mirror' ? options.mirrorApiUrl : options.proxyApiUrl;
+  const tierUrl = rewriteTransportUrl(url, resource, rawBase, apiBase);
+  if (!fetcher && !tierUrl) {
+    emit({ tier, code: `github.transport.${tier}.configured-unavailable`, severity: 'info', url, resource, message: `${tier} is configured conceptually but no browser reader for this request is available.` });
+    return null;
+  }
+  try {
+    const targetUrl = tierUrl || url;
+    emit({ tier, code: `github.transport.${tier}.try`, severity: 'info', url: targetUrl, originalUrl: url, resource });
+    const res = await (fetcher || options.fetchImpl)(targetUrl, init);
+    if (res?.ok) {
+      const text = await responseBodyText(res, resource);
+      emit({ tier, code: `github.transport.${tier}.ok`, severity: 'info', url: targetUrl, originalUrl: url, resource, status: res.status || 200 });
+      return makeResponse(text, { url: targetUrl, tier, status: res.status || 200, statusText: res.statusText || 'OK', contentType: contentTypeFor(resource) });
+    }
+    emit({ tier, code: `github.transport.${tier}.failed`, severity: 'warning', url: targetUrl, originalUrl: url, resource, status: res?.status || 0, message: res?.statusText || '' });
+  } catch (error) {
+    emit({ tier, code: `github.transport.${tier}.exception`, severity: 'warning', url, resource, message: messageOf(error) });
+  }
+  return null;
+}
+
+function rewriteTransportUrl(url, resource, rawBase, apiBase) {
+  const base = resource === 'api-json' ? apiBase : rawBase;
+  if (!base) return '';
+  const encoded = encodeURIComponent(url);
+  if (String(base).includes('{url}')) return String(base).replace('{url}', encoded).replace('{rawUrl}', encoded);
+  return `${String(base).replace(/\/+$/, '')}/${encoded}`;
+}
+
+function classifyGithubResource(url, init = {}) {
+  const text = String(url || '');
+  if (/api\.github\.com\/repos\//i.test(text)) return 'api-json';
+  if (/raw\.githubusercontent\.com\//i.test(text)) return 'raw-markdown';
+  if (/github\.com\/[^/]+\/[^/]+\/blob\//i.test(text)) return 'raw-markdown';
+  return /json/i.test(String(init?.headers?.Accept || init?.headers?.accept || '')) ? 'api-json' : 'source-resource';
+}
+
+function cacheKeyFor(url, resource) {
+  return `${SOURCE_CACHE_PREFIX}${resource}:${url}`;
+}
+
+function contentTypeFor(resource) {
+  return resource === 'api-json' ? 'application/json' : 'text/markdown; charset=utf-8';
+}
+
+function createSourceTextCache(options = {}) {
+  const memory = options.sourceCache || moduleMemoryCache;
+  const storage = options.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  const maxChars = Math.max(0, Number(options.maxCacheEntryChars || 750000));
+  return {
+    get(key) {
+      const mem = readObject(memory, key);
+      if (mem?.body != null) return mem;
+      try {
+        const raw = storage?.getItem?.(key);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (parsed?.body != null) {
+          writeObject(memory, key, parsed);
+          return parsed;
+        }
+      } catch (_) {}
+      return null;
+    },
+    async put(key, body, contentType) {
+      const text = String(body || '');
+      if (!text || (maxChars && text.length > maxChars)) return false;
+      const entry = { body: text, contentType, cachedAt: new Date().toISOString() };
+      writeObject(memory, key, entry);
+      try { storage?.setItem?.(key, JSON.stringify(entry)); } catch (_) {}
+      return true;
+    }
+  };
+}
+
+const moduleMemoryCache = Object.create(null);
+
+function readObject(store, key) {
+  if (!store) return null;
+  if (typeof store.get === 'function') return store.get(key) || null;
+  return store[key] || null;
+}
+
+function writeObject(store, key, value) {
+  if (!store) return;
+  if (typeof store.set === 'function') store.set(key, value);
+  else store[key] = value;
+}
+
+async function responseBodyText(response, resource = '') {
+  if (resource === 'api-json') {
+    try {
+      const body = typeof response.clone === 'function' ? await response.clone().json() : await response.json();
+      return JSON.stringify(body || {});
+    } catch (_) {}
+  }
+  return cloneResponseText(response);
+}
+
+async function cloneResponseText(response) {
+  if (!response) return '';
+  if (typeof response.clone === 'function') {
+    try { return await response.clone().text(); } catch (_) {}
+  }
+  if (typeof response.text === 'function') return response.text();
+  return String(response.body || '');
+}
+
+function makeResponse(body, options = {}) {
+  const text = String(body || '');
+  const ok = options.ok !== false && Number(options.status || 200) >= 200 && Number(options.status || 200) < 300;
+  return Object.freeze({
+    ok,
+    status: options.status || (ok ? 200 : 500),
+    statusText: options.statusText || (ok ? 'OK' : 'Error'),
+    url: options.url || '',
+    transportTier: options.tier || '',
+    headers: { get: (name) => String(name || '').toLowerCase() === 'content-type' ? (options.contentType || 'text/plain') : null },
+    text: async () => text,
+    json: async () => JSON.parse(text || '{}'),
+    clone: () => makeResponse(text, options)
+  });
+}
+
+function messageOf(error) {
+  return String(error && error.message ? error.message : error || 'unknown error');
+}

package/src/sources/local/local.source.js

@@ -0,0 +1 @@
+export function localSource(path) { return { kind: 'local', path }; }

package/src/sources/source.assetReferences.js

@@ -0,0 +1,109 @@
+export const SOURCE_ASSET_REFERENCE_SCHEMA_ID = 'tiinex.source.assetReference.discovery.v1';
+
+const ASSET_EXTENSIONS = /\.(png|jpe?g|gif|webp|svg|avif|bmp)$/i;
+
+export function collectSourceAssetReferences(records = [], options = {}) {
+  const source = options.source || {};
+  const available = new Set((Array.isArray(options.availablePaths) ? options.availablePaths : []).map((item) => canonicalPath(item)).filter(Boolean));
+  const references = [];
+  for (const record of Array.isArray(records) ? records : []) {
+    const markdown = String(record?.markdown || '');
+    if (!markdown) continue;
+    for (const ref of extractMarkdownAssetRefs(markdown)) {
+      const normalized = normalizeAssetReference(ref.target, record, source);
+      if (!normalized) continue;
+      const loaded = available.has(normalized.path);
+      references.push(Object.freeze({
+        schema: SOURCE_ASSET_REFERENCE_SCHEMA_ID,
+        recordId: record.id || '',
+        recordPath: record.path || '',
+        raw: ref.target,
+        label: ref.label || '',
+        path: normalized.path,
+        kind: normalized.kind,
+        status: normalized.blocked ? 'blocked' : (loaded ? 'loaded' : 'referenced-unloaded'),
+        boundary: normalized.boundary
+      }));
+    }
+  }
+  const counts = references.reduce((acc, item) => {
+    acc.total += 1;
+    acc[item.status] = (acc[item.status] || 0) + 1;
+    return acc;
+  }, { total: 0, loaded: 0, 'referenced-unloaded': 0, missing: 0, blocked: 0 });
+  return Object.freeze({ schema: SOURCE_ASSET_REFERENCE_SCHEMA_ID, references: Object.freeze(references), counts: Object.freeze(counts) });
+}
+
+export function extractMarkdownAssetRefs(markdown = '') {
+  const text = String(markdown || '');
+  const refs = [];
+  const imageRe = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  const linkRe = /(?<!!)\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  const htmlImgRe = /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi;
+  for (const match of text.matchAll(imageRe)) pushIfAsset(refs, match[2], match[1]);
+  for (const match of text.matchAll(linkRe)) pushIfAsset(refs, match[2], match[1]);
+  for (const match of text.matchAll(htmlImgRe)) pushIfAsset(refs, match[1], 'img');
+  return Object.freeze(refs.map((item) => Object.freeze(item)));
+}
+
+function pushIfAsset(out, target = '', label = '') {
+  const clean = String(target || '').trim();
+  if (!clean || clean.startsWith('#') || /^data:/i.test(clean)) return;
+  const withoutQuery = clean.split(/[?#]/)[0];
+  if (!ASSET_EXTENSIONS.test(withoutQuery)) return;
+  out.push({ target: clean, label: String(label || '').trim() });
+}
+
+function normalizeAssetReference(target = '', record = {}, source = {}) {
+  const raw = String(target || '').trim();
+  if (!raw) return null;
+  if (/^https?:\/\//i.test(raw)) {
+    return { path: raw, kind: 'external', blocked: false, boundary: 'external asset reference; not fetched by source materialization' };
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/i.test(raw)) return null;
+  const base = dirname(canonicalPath(record.path || ''));
+  const path = canonicalPath([base, raw].filter(Boolean).join('/'));
+  const roots = sourceRoots(source || record.source || {});
+  const blocked = roots.length ? !roots.some((root) => path === root || path.startsWith(`${root}/`)) : false;
+  return {
+    path,
+    kind: 'relative-source-asset',
+    blocked,
+    boundary: blocked
+      ? 'relative asset reference resolves outside configured source root boundary'
+      : 'relative asset reference inside configured source boundary; content not auto-fetched in this slice'
+  };
+}
+
+function sourceRoots(source = {}) {
+  return String(source.rootPath || source.config?.rootPath || '')
+    .split(/\r?\n|,/)
+    .map((item) => canonicalPath(item.trim().replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '')))
+    .filter((item) => item && item !== '.');
+}
+
+function dirname(path = '') {
+  const parts = canonicalPath(path).split('/').filter(Boolean);
+  parts.pop();
+  return parts.join('/');
+}
+
+function canonicalPath(value = '') {
+  let raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    raw = url.hostname === 'raw.githubusercontent.com'
+      ? url.pathname.split('/').filter(Boolean).slice(3).join('/')
+      : url.pathname.replace(/^\/+/, '');
+  } catch (error) {
+    // not a URL
+  }
+  const out = [];
+  for (const part of raw.replace(/\\/g, '/').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}

package/src/sources/source.boundaries.js

@@ -0,0 +1,24 @@
+import { isLocalSource, normalizeSourceRegistration } from './source.model.js';
+
+export function resolveSourceBoundary(source = {}) {
+  const normalized = normalizeSourceRegistration(source || {});
+  const local = isLocalSource(normalized);
+  const explicitGithub = normalized.adapterId === 'github' && Boolean(normalized.repo || normalized.config?.repo || normalized.permalink);
+  return {
+    kind: normalized.kind || normalized.sourceKind || 'draft',
+    adapterId: normalized.adapterId,
+    sourceKind: normalized.sourceKind,
+    label: normalized.label || normalized.sourceKind || normalized.adapterId || 'source',
+    sourceBacked: !local && Boolean(normalized.adapterId),
+    githubPolicy: explicitGithub ? 'explicit' : 'not-guessed',
+    disclosure: normalized.boundary || (local ? 'browser-local session material' : 'explicit source boundary'),
+    config: normalized.config
+  };
+}
+
+export function mustNotGuessGithubSource(source = {}) {
+  const normalized = normalizeSourceRegistration(source || {});
+  if (isLocalSource(normalized)) return true;
+  if (normalized.adapterId !== 'github') return true;
+  return Boolean(normalized.repo || normalized.config?.repo || normalized.permalink);
+}

package/src/sources/source.identity.js

@@ -0,0 +1,56 @@
+(function attachSourceIdentity(global) {
+  'use strict';
+  function sourceIdPart(value, fallback = 'unresolved', options = {}) {
+    const caseSensitive = options?.caseSensitive === true;
+    let text = String(value || '').trim();
+    if (!caseSensitive) text = text.toLowerCase();
+    return text
+      .replace(/^\.+\/?/, '')
+      .replace(/^\/+|\/+$/g, '')
+      .replace(caseSensitive ? /[^A-Za-z0-9._/-]+/g : /[^a-z0-9._/-]+/g, '-')
+      .replace(/\/{2,}/g, '/')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .replace(/\//g, '-') || fallback;
+  }
+  function canonicalSourcePath(value = '.topics') {
+    const out = [];
+    for (const part of String(value || '.topics').trim().replace(/\\/g, '/').replace(/\/{2,}/g, '/').split('/')) {
+      if (!part || part === '.') continue;
+      if (part === '..') out.pop();
+      else out.push(part);
+    }
+    return out.join('/') || '.topics';
+  }
+  function configuredSourceBoundaryParts(input = {}) {
+    const repository = String(input.repository || input.repo || input.config?.repo || '').trim().toLowerCase();
+    if (!repository) return null;
+    const ref = String(input.ref || input.requestedRef || input.config?.ref || '').trim();
+    const rootPath = canonicalSourcePath(input.rootPath || input.config?.rootPath || '.topics');
+    return Object.freeze({ repository, ref, rootPath });
+  }
+  function configuredSourceBoundaryKey(input = {}) {
+    const parts = configuredSourceBoundaryParts(input);
+    return parts ? JSON.stringify([parts.repository, parts.ref, parts.rootPath]) : '';
+  }
+  function configuredSourceBoundarySignature(input = {}) {
+    const parts = configuredSourceBoundaryParts(input);
+    return parts ? [parts.repository, parts.ref, parts.rootPath].join('|') : '';
+  }
+  function configuredSourceBoundaryIdentity(input = {}) {
+    const parts = configuredSourceBoundaryParts(input);
+    if (!parts) return null;
+    return Object.freeze({
+      ...parts,
+      key: configuredSourceBoundaryKey(parts),
+      signature: configuredSourceBoundarySignature(parts)
+    });
+  }
+  function makeConfiguredSourceId(input = {}) {
+    const repository = sourceIdPart(input.repository || input.repo || input.config?.repo, 'source');
+    const ref = sourceIdPart(input.ref || input.requestedRef || input.config?.ref, 'unresolved', { caseSensitive: true });
+    const rootPath = sourceIdPart(canonicalSourcePath(input.rootPath || input.config?.rootPath || '.topics'), 'root', { caseSensitive: true });
+    return `github:${repository}:${ref}:${rootPath}`;
+  }
+  global.TiinexSourceIdentity = { sourceIdPart, configuredSourceBoundaryParts, configuredSourceBoundaryKey, configuredSourceBoundarySignature, configuredSourceBoundaryIdentity, makeConfiguredSourceId };
+})(typeof window !== 'undefined' ? window : globalThis);