@tiinex/app 0.1.1

package/src/app/lineageCommand.js

@@ -0,0 +1,118 @@
+import { buildWorkspaceAuditView } from '../workspaces/workspace.auditView.js';
+import { buildWorkspaceLineageView } from '../workspaces/workspace.lineageView.js';
+import { recoverMissingLineageParentsFromSource } from './lineageSourceRecovery.js';
+
+export function lineageLoadReportForSelectedView(view = {}) {
+  const selectedRecordId = String(view.selectedRecordId || '').trim();
+  const report = view.lineageLoadReport || null;
+  return selectedRecordId && report && String(report.selectedRecordId || '') === selectedRecordId ? report : null;
+}
+
+export function lineageControlsReadyForTraversal(traversal = null) {
+  if (!traversal) return false;
+  const terminalState = String(traversal.terminalState || traversal.status?.terminalState || '').trim();
+  if (['root-reached', 'root-reached-scope-transition', 'no-parent-declared', 'target-unavailable', 'ambiguous-parent', 'integrity-mismatch'].includes(terminalState)) return true;
+  return traversal.complete === true;
+}
+
+export function shouldAutoLoadLineage({ workspace, selectedRecordId = '', existingLoadReport = null, loadedKeys = new Set() } = {}) {
+  const cleanId = String(selectedRecordId || '').trim();
+  if (!workspace || !cleanId || existingLoadReport) return { shouldLoad: false, key: '', lineage: null };
+  const lineage = buildWorkspaceLineageView(workspace, { records: Array.isArray(workspace?.records) ? workspace.records : [], query: '', selectedRecordId: cleanId });
+  const key = `${workspace.id || ''}:${cleanId}:${workspace.records?.length || 0}:${lineage.selectedTraversal?.missingEdges?.length || 0}`;
+  return { shouldLoad: Boolean(lineage.selectedTraversal?.hasMissing && !loadedKeys.has(key)), key, lineage };
+}
+
+export async function loadFullLineageCommand({ lifecycle, state, workspace, selectedRecordId = '', fetchImpl, workspaceConfig, clock = () => new Date().toISOString() } = {}) {
+  const cleanId = String(selectedRecordId || '').trim();
+  if (!workspace) return { ok: false, error: 'workspace.missing', message: 'No active workspace is available.', state };
+  if (!cleanId) return { ok: false, error: 'lineage.selection.required', message: 'Select an artifact lineage before loading lineage.', state };
+  const recovered = await recoverMissingLineageParentsFromSource({ lifecycle, state, workspace, selectedRecordId: cleanId, fetchImpl, workspaceConfig });
+  const sourceState = recovered.state || state;
+  const activeWorkspace = workspaceById(sourceState, workspace.id) || recovered.workspace || workspace;
+  const lineage = recovered.lineage || buildWorkspaceLineageView(activeWorkspace, { records: Array.isArray(activeWorkspace.records) ? activeWorkspace.records : [], query: '', selectedRecordId: cleanId });
+  const recoveredParents = Number(recovered.recoveredParents || 0);
+  const traversal = lineage.selectedTraversal || null;
+  const nodes = Array.isArray(traversal?.nodes) ? traversal.nodes : [];
+  const stateLabel = traversal?.complete ? 'complete' : 'partial';
+  const terminalState = traversal?.terminalState || traversal?.status?.terminalState || (stateLabel === 'complete' ? 'complete' : 'partial');
+  const scopeTransitions = Array.isArray(traversal?.scopeTransitions) ? traversal.scopeTransitions : [];
+  const lineageLoadReport = {
+    schema: 'tiinex.workspace.lineageLoadReport.v1',
+    selectedRecordId: cleanId,
+    mode: recoveredParents ? 'source-assisted-loaded-workspace' : 'loaded-workspace',
+    state: stateLabel,
+    terminalState,
+    statusLabel: traversal?.status?.label || '',
+    nodes: nodes.length,
+    rootReached: Boolean(traversal?.rootReached),
+    noParentDeclared: Boolean(traversal?.noParentDeclared),
+    hasMissing: Boolean(traversal?.hasMissing),
+    hasMismatch: Boolean(traversal?.hasMismatch),
+    ambiguous: Boolean(traversal?.ambiguous),
+    depthLimited: Boolean(traversal?.depthLimited),
+    scopeTransitions: scopeTransitions.length,
+    recoveredParents,
+    generatedAt: clock()
+  };
+  const notice = recoveredParents
+    ? `Loaded ${recoveredParents} declared parent artifact${recoveredParents === 1 ? '' : 's'} from the source boundary.`
+    : stateLabel === 'complete' ? 'Full loaded-workspace lineage index ready.' : 'Loaded lineage index is partial; terminal root was not proven.';
+  return { ok: true, state: sourceState, workspace: activeWorkspace, lineage, lineageLoadReport, recoveredParents, notice, commitMode: recoveredParents ? 'push' : 'replace' };
+}
+
+export function runLineageAuditCommand({ state, workspace, selectedRecordId = '', query = '', existingLoadReport = null, clock = () => new Date().toISOString() } = {}) {
+  const cleanId = String(selectedRecordId || '').trim();
+  const records = Array.isArray(workspace?.records) ? workspace.records : [];
+  if (!workspace) return { ok: false, error: 'workspace.missing', message: 'No active workspace is available.', state };
+  if (!cleanId) return { ok: false, error: 'lineage.selection.required', message: 'Select an artifact lineage before running Audit.', state };
+  const lineage = buildWorkspaceLineageView(workspace, { records, query, selectedRecordId: cleanId });
+  if (!existingLoadReport && !lineageControlsReadyForTraversal(lineage.selectedTraversal)) return { ok: false, error: 'lineage.load.required', message: 'Load full lineage before running Audit.', state, lineage };
+  const audit = buildWorkspaceAuditView(workspace, { records, query: '' });
+  const auditById = new Map((audit.items || []).map((item) => [item.id, item]));
+  const traversalNodes = Array.isArray(lineage.selectedTraversal?.nodes) && lineage.selectedTraversal.nodes.length
+    ? lineage.selectedTraversal.nodes
+    : records.filter((record) => record.id === cleanId).map((record) => ({ id: record.id, record }));
+  const counts = { ok: 0, mismatch: 0, open: 0, pending: 0 };
+  for (const node of traversalNodes) {
+    const id = String(node.id || node.record?.id || '');
+    const item = auditById.get(id);
+    const status = String(item?.status || '').toLowerCase();
+    if (status === 'readable' && !item?.fallbackUsed) counts.ok += 1;
+    else if (status === 'pending-unavailable') counts.pending += 1;
+    else if (status === 'readable' || status === 'degraded' || item?.fallbackUsed || !status) counts.open += 1;
+    else counts.mismatch += 1;
+  }
+  const loadReport = existingLoadReport || {
+    selectedRecordId: cleanId,
+    state: lineage.selectedTraversal?.complete ? 'complete' : 'partial',
+    terminalState: lineage.selectedTraversal?.terminalState || lineage.selectedTraversal?.status?.terminalState || '',
+    rootReached: Boolean(lineage.selectedTraversal?.rootReached),
+    noParentDeclared: Boolean(lineage.selectedTraversal?.noParentDeclared),
+    hasMissing: Boolean(lineage.selectedTraversal?.hasMissing),
+    hasMismatch: Boolean(lineage.selectedTraversal?.hasMismatch),
+    ambiguous: Boolean(lineage.selectedTraversal?.ambiguous),
+    depthLimited: Boolean(lineage.selectedTraversal?.depthLimited),
+    scopeTransitions: Array.isArray(lineage.selectedTraversal?.scopeTransitions) ? lineage.selectedTraversal.scopeTransitions.length : 0
+  };
+  const auditState = loadReport?.state === 'complete' && lineage.selectedTraversal?.complete ? 'complete' : 'partial';
+  const lineageAuditReport = {
+    schema: 'tiinex.workspace.lineageAuditInline.v1',
+    selectedRecordId: cleanId,
+    state: auditState,
+    terminalState: lineage.selectedTraversal?.terminalState || loadReport?.terminalState || '',
+    statusLabel: lineage.selectedTraversal?.status?.label || loadReport?.statusLabel || '',
+    nodes: traversalNodes.length,
+    rootReached: Boolean(lineage.selectedTraversal?.rootReached),
+    noParentDeclared: Boolean(lineage.selectedTraversal?.noParentDeclared),
+    hasMissing: Boolean(lineage.selectedTraversal?.hasMissing),
+    scopeTransitions: Array.isArray(lineage.selectedTraversal?.scopeTransitions) ? lineage.selectedTraversal.scopeTransitions.length : Number(loadReport?.scopeTransitions || 0),
+    counts,
+    generatedAt: clock()
+  };
+  return { ok: true, state, workspace, lineage, lineageAuditReport };
+}
+
+function workspaceById(state = {}, workspaceId = '') {
+  return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => workspace.id === workspaceId) || null;
+}

package/src/app/lineageSourceRecovery.js

@@ -0,0 +1,339 @@
+import { materializeGithubSource } from '../adapters/github/github.adapter.js';
+import { buildSourceTransportPolicy } from '../sources/transport.policy.js';
+import { githubTransportOrderFromTier } from '../sources/github/github.transport.js';
+import { buildWorkspaceLineageView } from '../workspaces/workspace.lineageView.js';
+import { lineageBasePathForRecord } from '@tiinex/core/lineage/lineage.pathBasis.js';
+import { githubFileRefsForRecord, githubIssueUrlsForRecord, parseOriginReferenceValue, recoverySourceForRecord } from '@tiinex/core/sources/origin.references.js';
+
+const GITHUB_ADAPTER_ID = 'github';
+
+export async function recoverMissingLineageParentsFromSource({ lifecycle, state, workspace, selectedRecordId, fetchImpl, workspaceConfig, maxPasses = 4 } = {}) {
+  let sourceState = state;
+  let activeWorkspace = workspace;
+  let lineage = buildWorkspaceLineageView(activeWorkspace, { records: Array.isArray(activeWorkspace?.records) ? activeWorkspace.records : [], query: '', selectedRecordId });
+  let recoveredParents = 0;
+  for (let pass = 0; pass < maxPasses; pass += 1) {
+    const recoveryPlan = buildLineageSourceRecoveryPlan(activeWorkspace, lineage);
+    if (!recoveryPlan.length) break;
+    let changed = false;
+    for (const plan of recoveryPlan) {
+      const out = await materializeLineageRecoveryPlan(plan, { fetchImpl, workspaceConfig });
+      if (out.okCount <= 0) continue;
+      const registered = ensureLineageRecoverySource(lifecycle, sourceState, activeWorkspace.id, plan.source);
+      sourceState = registered.state || sourceState;
+      activeWorkspace = registered.workspace || activeWorkspace;
+      const inserted = lifecycle?.addWorkspaceSourceRecords?.(sourceState, activeWorkspace.id, plan.sourceId, out.records || [], { discoveryState: 'partial', preserveView: true });
+      if (!inserted?.ok) continue;
+      sourceState = inserted.state;
+      activeWorkspace = lifecycle?.activeWorkspace?.(sourceState) || inserted.workspace || activeWorkspace;
+      recoveredParents += Number(inserted.records?.length || 0);
+      changed = true;
+    }
+    lineage = buildWorkspaceLineageView(activeWorkspace, { records: Array.isArray(activeWorkspace.records) ? activeWorkspace.records : [], query: '', selectedRecordId });
+    if (!changed || !lineage.selectedTraversal?.hasMissing) break;
+  }
+  return { state: sourceState, workspace: activeWorkspace, lineage, recoveredParents };
+}
+
+
+export function ensureLineageRecoverySource(lifecycle, state = {}, workspaceId = '', source = {}) {
+  const cleanId = String(source?.id || '').trim();
+  if (!cleanId || !source || typeof source !== 'object') return { state, workspace: workspaceById(state, workspaceId) || lifecycle?.activeWorkspace?.(state) || null, inserted: false };
+  const currentWorkspace = workspaceById(state, workspaceId) || lifecycle?.activeWorkspace?.(state) || null;
+  if (!currentWorkspace) return { state, workspace: null, inserted: false };
+  const existing = (Array.isArray(currentWorkspace.sources) ? currentWorkspace.sources : []).find((item) => String(item?.id || '') === cleanId);
+  if (existing) return { state, workspace: currentWorkspace, inserted: false, source: existing };
+  const next = typeof lifecycle?.cloneState === 'function' ? lifecycle.cloneState(state) : JSON.parse(JSON.stringify(state || {}));
+  const workspace = workspaceById(next, workspaceId) || lifecycle?.activeWorkspace?.(next) || null;
+  if (!workspace) return { state, workspace: currentWorkspace, inserted: false };
+  const recoverySource = normalizeLineageRecoverySource(source);
+  workspace.sources = (Array.isArray(workspace.sources) ? workspace.sources.slice() : []).filter((item) => String(item?.id || '') !== cleanId);
+  workspace.sources.push(recoverySource);
+  workspace.sourceOrder = workspace.sources.map((item) => item.id).filter(Boolean);
+  next.activeWorkspaceId = workspace.id || next.activeWorkspaceId || workspaceId;
+  return { state: next, workspace, inserted: true, source: recoverySource };
+}
+
+function normalizeLineageRecoverySource(source = {}) {
+  const repo = String(source.repo || source.repository || source.config?.repo || '').trim();
+  const ref = String(source.ref || source.config?.ref || '').trim();
+  const rootPath = String(source.rootPath || source.config?.rootPath || '.topics').trim() || '.topics';
+  return Object.assign({}, source, {
+    id: String(source.id || '').trim(),
+    kind: source.kind || 'github-tree',
+    adapterId: source.adapterId || 'github',
+    sourceKind: source.sourceKind || (source.originReferenceSource ? 'github.origin-reference' : 'github.repo'),
+    repo,
+    repository: String(source.repository || repo || '').trim(),
+    ref,
+    rootPath,
+    config: Object.assign({}, source.config || {}, { repo, ref, rootPath }),
+    discoveryState: source.discoveryState || 'deferred',
+    recoveryOnly: source.recoveryOnly === true || source.originReferenceSource === true,
+    sourceBacked: source.sourceBacked === false ? false : source.originReferenceSource === true ? false : true,
+    originReferenceSource: source.originReferenceSource === true || source.sourceKind === 'github.origin-reference',
+    closeable: source.closeable !== false
+  });
+}
+
+async function materializeLineageRecoveryPlan(plan = {}, { fetchImpl, workspaceConfig } = {}) {
+  const fileRefs = Array.isArray(plan.fileRefs) ? plan.fileRefs : [];
+  const issueUrls = Array.isArray(plan.issueUrls) ? plan.issueUrls : [];
+  if (issueUrls.length) {
+    const requestedTier = plan.source?.transportRefreshTier || plan.source?.preferredTransportTier || '';
+    const transportOrder = requestedTier ? githubTransportOrderFromTier(requestedTier) : undefined;
+    return await materializeGithubSource(plan.source, { fileRefs: [], repoDiscovery: false, issueDiscovery: false, issueUrls: issueUrls.join('\n') }, {
+      fetchImpl,
+      maxFiles: 0,
+      allowCache: true, allowMirror: true, allowProxy: true, allowDirect: true,
+      transportOrder, transportOrderExact: Boolean(requestedTier),
+      transportRefreshTier: requestedTier,
+      transportPolicy: buildSourceTransportPolicy({ mode: 'targeted-parent-issue-recovery', maxRequestsPerOperation: 64, requestedTier, now: new Date().toISOString() }),
+      workspaceConfig
+    });
+  }
+  return await materializeGithubSource(plan.source, { fileRefs, repoDiscovery: false, issueDiscovery: false, issueUrls: '' }, {
+    fetchImpl,
+    maxFiles: 32,
+    allowCache: false, allowMirror: false, allowProxy: false, allowDirect: true,
+    transportOrder: ['direct'], transportOrderExact: true,
+    transportPolicy: buildSourceTransportPolicy({ mode: 'targeted-parent-file-recovery', maxRequestsPerOperation: 64, now: new Date().toISOString() }),
+    workspaceConfig
+  });
+}
+
+export function buildLineageSourceRecoveryPlan(workspace = {}, lineageView = {}) {
+  const records = Array.isArray(workspace.records) ? workspace.records : [];
+  const byId = new Map(records.map((record) => [String(record.id || '').trim(), record]));
+  const missingEdges = Array.isArray(lineageView?.selectedTraversal?.missingEdges) ? lineageView.selectedTraversal.missingEdges : [];
+  const grouped = new Map();
+  for (const edge of missingEdges) {
+    const declaring = byId.get(String(edge.to || '').trim());
+    const source = recoverySourceForLineageTarget(edge.target || '', declaring, workspace);
+    if (!isGithubSource(source)) continue;
+    const sourceId = String(source.id || '').trim();
+    if (!sourceId) continue;
+    if (!grouped.has(sourceId)) grouped.set(sourceId, { sourceId, source, fileRefs: [], issueUrls: [], targets: [] });
+    const entry = grouped.get(sourceId);
+    const issueUrl = lineageRecoveryIssueUrlForTarget(edge.target || '', declaring);
+    if (issueUrl && !entry.issueUrls.some((item) => canonicalGithubIssueUrl(item) === canonicalGithubIssueUrl(issueUrl))) {
+      entry.issueUrls.push(issueUrl);
+      entry.targets.push({ fromRecordId: declaring?.id || '', target: edge.target || '', issueUrl });
+      continue;
+    }
+    const fileRef = lineageRecoveryFileRefForTarget(edge.target || '', declaring);
+    if (!fileRef) continue;
+    if (!entry.fileRefs.some((item) => canonicalRepoPath(item.ref || item) === canonicalRepoPath(fileRef))) {
+      entry.fileRefs.push({ ref: fileRef, surface: 'lineageRecovery', targetKind: 'lineage-parent', inputTarget: edge.target || '', targetIndex: entry.fileRefs.length });
+      entry.targets.push({ fromRecordId: declaring?.id || '', target: edge.target || '', fileRef });
+    }
+  }
+  return Array.from(grouped.values()).filter((entry) => entry.fileRefs.length || entry.issueUrls.length);
+}
+
+
+export function recoverySourceForLineageTarget(target = '', record = {}, workspace = {}) {
+  const ref = parseOriginReferenceValue(target);
+  if (ref?.provider === 'github' && ref.repository && ref.kind === 'github-file') {
+    const repository = String(ref.repository || '').trim();
+    const existing = (Array.isArray(workspace?.sources) ? workspace.sources : []).find((source) => {
+      const sourceRepo = String(source?.repo || source?.repository || source?.config?.repo || '').trim().toLowerCase();
+      return sourceRepo && sourceRepo === repository.toLowerCase() && isGithubSource(source);
+    });
+    if (existing) return Object.assign({}, existing, { ref: existing.ref || existing.config?.ref || ref.ref || '' });
+    const id = `origin:github:${repository.toLowerCase().replace(/[^a-z0-9/_-]+/g, '-').replace(/\//g, ':')}`;
+    const sourceRef = String(ref.ref || '').trim();
+    return {
+      id,
+      kind: 'github-tree',
+      adapterId: 'github',
+      sourceKind: 'github.origin-reference',
+      label: `GitHub parent · ${repository}`,
+      roleLabel: 'lineage recovery only',
+      repo: repository,
+      repository,
+      ref: sourceRef,
+      rootPath: '.topics',
+      config: { repo: repository, ref: sourceRef, rootPath: '.topics', issueUrls: '', fileRefs: ref.path || '' },
+      count: 0,
+      sourceBacked: false,
+      originReferenceSource: true,
+      recoveryOnly: true,
+      closeable: true,
+      discoveryState: 'deferred',
+      boundary: 'explicit external Parent Trace; recovery only until exact source material is loaded',
+      transportLabel: 'Parent recovery only',
+      loadable: false,
+      transportRefreshTier: 'direct'
+    };
+  }
+  return recoverySourceForRecord(record, workspace);
+}
+
+export function lineageRecoveryIssueUrlForTarget(target = '', declaringRecord = {}) {
+  const raw = String(target || '').trim();
+  const explicitParent = firstNonEmpty(
+    declaringRecord?.sourceTarget?.parentRawUrl,
+    declaringRecord?.sourceTarget?.parentSourceUrl,
+    declaringRecord?.snapshot?.parentRawUrl,
+    declaringRecord?.snapshot?.parentSourceUrl
+  );
+  if (isGitHubSocialTarget(explicitParent) && parentSocialTargetMatchesTrace(explicitParent, raw)) return explicitParent;
+  if (isGitHubSocialTarget(raw)) return raw;
+  for (const url of githubIssueUrlsForRecord(declaringRecord)) {
+    if (isGitHubSocialTarget(url) && parentSocialTargetMatchesTrace(url, raw)) return url;
+  }
+  const origin = firstNonEmpty(declaringRecord?.origin || '', declaringRecord?.parentOrigin || '');
+  if (isGitHubSocialTarget(origin) && parentSocialTargetMatchesTrace(origin, raw)) return origin;
+  return '';
+}
+
+export function lineageRecoveryFileRefForTarget(target = '', declaringRecord = {}) {
+  const raw = String(target || '').trim();
+  if (!raw || /^record:/i.test(raw)) return '';
+  if (isGitHubSocialTarget(raw)) return '';
+  const declaredParent = declaredParentFileRef(declaringRecord, raw);
+  if (declaredParent) return declaredParent;
+  const urlPath = githubRepoRelativePathFromUrl(raw);
+  if (urlPath) return urlPath;
+  if (isUrlLike(raw)) return '';
+  const cleanTarget = canonicalRepoPath(raw);
+  if (!cleanTarget) return '';
+  if (isDotRelative(raw) || isSimpleRelative(raw)) {
+    const declaringPath = lineageBasePathForRecord(declaringRecord);
+    const dir = dirname(githubRepoRelativePathFromUrl(declaringPath) || declaringPath);
+    return canonicalRepoPath(dir ? `${dir}/${raw}` : cleanTarget);
+  }
+  return cleanTarget;
+}
+
+
+
+function declaredParentFileRef(record = {}, target = '') {
+  const explicitParent = firstNonEmpty(record?.sourceTarget?.parentRawUrl, record?.sourceTarget?.parentSourceUrl, record?.snapshot?.parentRawUrl, record?.snapshot?.parentSourceUrl, record?.sourceTarget?.parentArtifactPath, record?.snapshot?.parentArtifactPath);
+  const explicit = recoverableParentFileRef(explicitParent, target, { allowRelative: isSyntheticPublicationRecord(record) });
+  if (explicit) return explicit;
+  for (const ref of githubFileRefsForRecord(record)) {
+    const explicitRef = recoverableParentFileRef(ref, target, { allowRelative: false });
+    if (explicitRef) return explicitRef;
+  }
+  const origin = recoverableParentFileRef(record?.origin || record?.parentOrigin || '', target, { allowRelative: false });
+  if (origin) return origin;
+  return '';
+}
+function recoverableParentFileRef(parent = '', target = '', options = {}) {
+  if (!parent || isGitHubSocialTarget(parent)) return '';
+  const fromUrl = githubRepoRelativePathFromUrl(parent);
+  if (fromUrl && originMatchesTarget(fromUrl, target)) return fromUrl;
+  if (isUrlLike(parent)) return '';
+  const clean = canonicalRepoPath(parent);
+  if (!clean || !isRecoverableRepoPathCandidate(parent, clean, options) || !originMatchesTarget(clean, target)) return '';
+  return clean;
+}
+function originMatchesTarget(originPath = '', target = '') {
+  const origin = canonicalRepoPath(originPath);
+  const cleanTarget = canonicalRepoPath(target);
+  if (!origin) return false;
+  if (!cleanTarget) return true;
+  if (origin === cleanTarget || origin.endsWith('/' + cleanTarget)) return true;
+  const originBase = basename(origin);
+  const targetBase = basename(cleanTarget);
+  return Boolean(originBase && targetBase && originBase === targetBase);
+}
+function parentSocialTargetMatchesTrace(parentUrl = '', target = '') {
+  if (!parentUrl) return false;
+  const parentComment = githubIssueCommentIdFromValue(parentUrl);
+  const targetComment = githubIssueCommentIdFromValue(target);
+  if (parentComment && targetComment) return parentComment === targetComment;
+  if (isGitHubSocialTarget(target)) return canonicalGithubIssueUrl(parentUrl) === canonicalGithubIssueUrl(target);
+  return true;
+}
+function githubIssueCommentIdFromValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  const direct = raw.match(/(?:issuecomment-|issues\/comments\/|comment-(?:\d+-)?)(\d{4,})/i)?.[1] || '';
+  if (direct) return direct;
+  try { const url = new URL(raw); return url.hash.match(/issuecomment-(\d+)/i)?.[1] || ''; } catch (_) {}
+  return '';
+}
+function canonicalGithubIssueUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 4 && parts[2] === 'issues') {
+      const hash = url.hash.match(/issuecomment-(\d+)/i)?.[1] || '';
+      return `https://github.com/${parts[0].toLowerCase()}/${parts[1].toLowerCase()}/issues/${parts[3]}${hash ? `#issuecomment-${hash}` : ''}`;
+    }
+  } catch (_) {}
+  return String(value || '').trim().toLowerCase();
+}
+
+function isRecoverableRepoPathCandidate(raw = '', clean = '', options = {}) {
+  const text = String(raw || '').trim().replace(/\\/g, '/');
+  if (/^\.topics(?:\/|$)/.test(clean)) return true;
+  if (options.allowRelative && /^\.\.?\//.test(text)) return true;
+  if (options.allowRelative && clean.includes('/')) return true;
+  return false;
+}
+function isSyntheticPublicationRecord(record = {}) {
+  const mode = String(record.sourceMode || record.recoveryKind || '').toLowerCase();
+  const targetKind = String(record.sourceTarget?.targetKind || record.snapshot?.sourceKind || '').toLowerCase();
+  const path = canonicalRepoPath(record.path || '');
+  return Boolean(
+    mode.includes('github-issue') ||
+    mode.includes('github-comment') ||
+    targetKind.includes('github-issue') ||
+    targetKind.includes('github-comment') ||
+    path.includes('/.issues/') ||
+    path.includes('/.github/.issues/')
+  );
+}
+function isGithubSource(source = {}) {
+  const candidate = source || {};
+  const adapter = String(candidate.adapterId || candidate.sourceKind || candidate.kind || '').toLowerCase();
+  return adapter.includes(GITHUB_ADAPTER_ID) || Boolean(candidate.repo || candidate.repository || candidate.config?.repo);
+}
+function firstNonEmpty(...items) { return items.map((item) => String(item || '').trim()).find(Boolean) || ''; }
+function isUrlLike(value = '') { return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(String(value || '').trim()); }
+function isGitHubSocialTarget(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    return (url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 4 && parts[2] === 'issues';
+  } catch (_) { return false; }
+}
+function githubRepoRelativePathFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 4) return canonicalRepoPath(parts.slice(3).join('/'));
+    if (url.hostname === 'github.com' && parts.length >= 5 && parts[2] === 'blob') return canonicalRepoPath(parts.slice(4).join('/'));
+  } catch (_) {}
+  return '';
+}
+function isDotRelative(value = '') { return /^\.\.?(?:\/|$)/.test(String(value || '').replace(/\\/g, '/').trim()); }
+function isSimpleRelative(value = '') {
+  const raw = String(value || '').trim();
+  return Boolean(raw && !raw.includes('/') && !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw));
+}
+function basename(path = '') { return canonicalRepoPath(path).split('/').filter(Boolean).pop() || ''; }
+function dirname(path = '') {
+  const parts = canonicalRepoPath(path).split('/').filter(Boolean);
+  parts.pop();
+  return parts.join('/');
+}
+function canonicalRepoPath(value = '') {
+  const out = [];
+  for (const part of String(value || '').replace(/^record:/i, '').replace(/\\/g, '/').split('/')) {
+    const clean = part.trim();
+    if (!clean || clean === '.') continue;
+    if (clean === '..') out.pop();
+    else out.push(clean);
+  }
+  return out.join('/');
+}
+
+function workspaceById(state = {}, workspaceId = '') {
+  const cleanId = String(workspaceId || '').trim();
+  return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => String(workspace?.id || '') === cleanId) || null;
+}

package/src/app/localDraftMutationCommand.js

@@ -0,0 +1,174 @@
+import { parseArtifactMarkdown } from '@tiinex/core/artifacts/artifact.parse.js';
+import { canDiscardLocalDraft, canEditLocalDraft, artifactSchemaId } from '@tiinex/core/artifacts/artifact.localDraft.js';
+import { resolveSchemaModule } from '@tiinex/core/schemas/resolver.js';
+import { durableLocalMutationDecision, DurableLocalMutationOperation } from './durableLocalMutationPolicy.js';
+import { validateLegacyTaskDraftCompatibility } from '@tiinex/core/schemas/core/task/tiinex.task.v1.validate.js';
+import { canonicalC14nV2SelfState, sealC14nV2Self } from '@tiinex/core/integrity/integrity.c14nV2.js';
+
+export const LOCAL_DRAFT_MUTATION_COMMAND_SCHEMA_ID = 'tiinex.local-draft.mutation-command.v1';
+
+export function runLocalDraftUpdateCommand({ lifecycle, state = {}, workspaceId = '', recordId = '', candidate = {}, persistenceOwnership = null } = {}) {
+  const authority = durableLocalMutationDecision(persistenceOwnership, DurableLocalMutationOperation.localDraftCreate);
+  if (!authority.ok) return refusal(authority.error, state, authority.notice, authority);
+  const context = recordContext(state, workspaceId, recordId);
+  if (!context.ok) return refusal(context.error, state, context.notice);
+  const original = context.record;
+  if (!canEditLocalDraft(original)) return refusal('record.edit.refused', state, 'Only supported browser-local drafts can be edited.');
+  if (!lifecycle?.addWorkspaceRecord) return refusal('lifecycle.missing', state, 'Could not update local draft.');
+  const markdown = String(candidate?.markdown || '').trim();
+  if (!markdown) return refusal('record.edit.markdown.required', state, 'Edited draft Markdown is required.');
+
+  let before, after;
+  try { before = parseArtifactMarkdown(original.markdown || ''); after = parseArtifactMarkdown(markdown); }
+  catch (_) { return refusal('record.edit.markdown.invalid', state, 'Edited draft Markdown could not be parsed.'); }
+
+  const invariantError = validateStableEditIdentity(original, candidate, before, after);
+  if (invariantError) return refusal(invariantError.code, state, invariantError.notice);
+  if (!String(after.envelope?.current?.summary || '').trim()) return refusal('record.edit.summary.required', state, 'Task Summary cannot be empty during local draft edit.');
+  const schemaId = artifactSchemaId(original);
+  const legacyTask = schemaId === 'tiinex.task.v1' && String(original.sourceMode || '') === 'local-transition';
+  const canonicalTask = schemaId === 'tiinex.task.v1' && String(original.sourceMode || '') === 'local-transition-canonical';
+  const resolution = resolveSchemaModule({ schemaId });
+  if (!legacyTask && (resolution.fallbackUsed || typeof resolution.module?.validate !== 'function')) return refusal('record.edit.validator.unavailable', state, `No exact validator is available for ${schemaId || 'this draft'}.`);
+  const findings = legacyTask ? validateLegacyTaskDraftCompatibility(after) : (resolution.module.validate(after) || []);
+  const errors = findings.filter((finding) => finding?.severity === 'error');
+  if (errors.length) return { ok: false, error: 'record.edit.validation.failed', state, notice: legacyTask ? 'Edited legacy Task draft no longer satisfies its compatibility shape.' : 'Edited draft does not satisfy its schema.', findings, validationQualification: legacyTask ? 'legacy-compatibility' : 'exact-current-schema' };
+
+  let committedMarkdown = markdown;
+  let integrity = null;
+  if (canonicalTask) {
+    const sealed = sealC14nV2Self(markdown);
+    if (sealed.state !== 'sealed') return refusal('record.edit.integrity.seal-unavailable', state, 'Edited canonical Task could not refresh its self-integrity proof.');
+    committedMarkdown = sealed.markdown;
+    integrity = canonicalC14nV2SelfState(committedMarkdown);
+    if (integrity.state !== 'verified') return refusal('record.edit.integrity.not-verified', state, 'Edited canonical Task self-integrity could not be verified.');
+    after = parseArtifactMarkdown(committedMarkdown);
+  }
+
+  const sanitized = buildEditedLocalDraftRecord(original, after, committedMarkdown, schemaId);
+  const result = lifecycle.addWorkspaceRecord(state, context.workspace.id, sanitized);
+  if (!result?.ok) return refusal(result?.error || 'record.edit.commit.failed', state, 'Could not update local draft.');
+  if (String(result.record?.id || '') !== String(original.id || '') || String(result.record?.path || '') !== String(original.path || '')) return refusal('record.edit.identity.commit-drift', state, 'Local draft identity changed during update.');
+  return { ok: true, schema: LOCAL_DRAFT_MUTATION_COMMAND_SCHEMA_ID, state: result.state, workspace: result.workspace, record: result.record, findings, validationQualification: legacyTask ? 'legacy-compatibility' : 'exact-current-schema', integrity, notice: `Updated local draft ${result.record?.title || original.title || 'artifact'}.` };
+}
+
+export function runLocalDraftDiscardCommand({ lifecycle, state = {}, workspaceId = '', recordId = '', persistenceOwnership = null } = {}) {
+  const authority = durableLocalMutationDecision(persistenceOwnership, DurableLocalMutationOperation.localDraftDelete);
+  if (!authority.ok) return refusal(authority.error, state, authority.notice, authority);
+  const context = recordContext(state, workspaceId, recordId);
+  if (!context.ok) return refusal(context.error, state, context.notice);
+  if (!canDiscardLocalDraft(context.record)) return refusal('record.remove.refused', state, 'Only browser-local drafts can be discarded.');
+  if (!lifecycle?.removeWorkspaceRecord) return refusal('lifecycle.missing', state, 'Could not discard local draft.');
+  const result = lifecycle.removeWorkspaceRecord(state, context.workspace.id, context.record.id);
+  if (!result?.ok) return refusal(result?.error || 'record.remove.failed', state, 'Could not discard local draft.');
+  return { ok: true, schema: LOCAL_DRAFT_MUTATION_COMMAND_SCHEMA_ID, state: result.state, workspace: result.workspace, record: result.record, notice: `Removed local draft ${result.record?.title || result.record?.path || 'artifact'} from this browser session.` };
+}
+
+function buildEditedLocalDraftRecord(original = {}, parsed = {}, markdown = '', schemaId = '') {
+  return Object.assign({}, original, {
+    id: original.id,
+    path: original.path,
+    schemaId: original.schemaId || schemaId,
+    kind: original.kind || schemaId,
+    createdAt: original.createdAt,
+    sourceMode: original.sourceMode,
+    source: original.source,
+    markdown,
+    title: parsed.title,
+    summary: parsed.envelope?.current?.summary ?? ''
+  });
+}
+
+function validateStableEditIdentity(original = {}, candidate = {}, before = {}, after = {}) {
+  const candidateSchema = explicitRecordSchemaMetadata(candidate);
+  const originalSchema = explicitRecordSchemaMetadata(original);
+  const checks = [
+    ['record.edit.id.changed', candidate.id, original.id, 'Record identity cannot change during local draft edit.'],
+    ['record.edit.path.changed', candidate.path, original.path, 'Draft path cannot change during local draft edit.'],
+    ['record.edit.kind.changed', candidate.kind, original.kind, 'Record representation kind cannot change during local draft edit.'],
+    ['record.edit.schema.changed', candidateSchema.present ? candidateSchema.value : undefined, originalSchema.value, 'Schema metadata cannot change during local draft edit.'],
+    ['record.edit.current-schema.changed', after.envelope?.current?.schema?.id, before.envelope?.current?.schema?.id, 'Current Schema cannot change during local draft edit.'],
+    ['record.edit.created-at.changed', after.envelope?.current?.createdAt, before.envelope?.current?.createdAt, 'Original Created At must remain stable during local draft edit.'],
+    ['record.edit.parent-schema.changed', after.envelope?.parent?.schema?.id, before.envelope?.parent?.schema?.id, 'Parent Schema cannot change during local draft edit.'],
+    ['record.edit.parent-trace.changed', after.envelope?.parent?.trace, before.envelope?.parent?.trace, 'Parent Trace cannot change during local draft edit.'],
+    ['record.edit.parent-origin.changed', after.envelope?.parent?.origin, before.envelope?.parent?.origin, 'Parent Origin cannot change during local draft edit.'],
+    ['record.edit.parent-boundary.changed', after.envelope?.parent?.boundary, before.envelope?.parent?.boundary, 'Parent Boundary cannot change during local draft edit.']
+  ];
+  for (const [code, actual, expected, notice] of checks) {
+    if (actual !== undefined && String(actual || '') !== String(expected || '')) return { code, notice };
+  }
+  const beforeShell = losslessEditShell(before.markdown || original.markdown || '');
+  const afterShell = losslessEditShell(after.markdown || candidate.markdown || '');
+  if (afterShell !== beforeShell) {
+    return { code: 'record.edit.continuity-shell.changed', notice: 'Continuity, provenance, status, schema locators, and integrity declarations cannot change during local Task edit.' };
+  }
+  return null;
+}
+
+
+function explicitRecordSchemaMetadata(record = {}) {
+  if (!record || typeof record !== 'object') return { present: false, value: '' };
+  if (Object.prototype.hasOwnProperty.call(record, 'schemaId')) return { present: true, value: String(record.schemaId || '').trim() };
+  if (Object.prototype.hasOwnProperty.call(record, 'currentSchemaId')) return { present: true, value: String(record.currentSchemaId || '').trim() };
+  if (record.rootFallback && typeof record.rootFallback === 'object' && Object.prototype.hasOwnProperty.call(record.rootFallback, 'currentSchemaId')) {
+    return { present: true, value: String(record.rootFallback.currentSchemaId || '').trim() };
+  }
+  return { present: false, value: '' };
+}
+
+function losslessEditShell(markdown = '') {
+  const sections = rawArtifactSections(markdown);
+  return [
+    maskEditableCurrentSummary(sections.envelope),
+    '---TIINEX-INTEGRITY---',
+    normalizeProtectedSection(sections.integrity)
+  ].join('\n');
+}
+
+function rawArtifactSections(markdown = '') {
+  const text = normalizeMarkdownLineEndings(markdown).trim();
+  const boundary = /^---\s*$/m.exec(text);
+  const envelope = boundary ? text.slice(0, boundary.index) : text;
+  if (!boundary) return { envelope: normalizeProtectedSection(envelope), integrity: '' };
+  const remainder = text.slice(boundary.index + boundary[0].length).replace(/^\n/, '');
+  const integrityIndex = remainder.search(/^# Continuity Integrity\s*$/m);
+  return {
+    envelope: normalizeProtectedSection(envelope),
+    integrity: integrityIndex === -1 ? '' : normalizeProtectedSection(remainder.slice(integrityIndex))
+  };
+}
+
+function maskEditableCurrentSummary(envelope = '') {
+  const lines = normalizeMarkdownLineEndings(envelope).split('\n');
+  const currentStart = lines.findIndex((line) => /^-\s+Current\s*$/.test(line));
+  if (currentStart === -1) return normalizeProtectedSection(envelope);
+  let currentEnd = lines.length;
+  for (let index = currentStart + 1; index < lines.length; index += 1) {
+    if (/^-\s+\S/.test(lines[index])) { currentEnd = index; break; }
+  }
+  for (let index = currentStart + 1; index < currentEnd; index += 1) {
+    const summary = lines[index].match(/^(\s+)-\s*Summary:\s*(.*)$/);
+    if (!summary) continue;
+    lines[index] = `${summary[1]}- Summary: __TIINEX_EDITABLE_CURRENT_SUMMARY__`;
+    break;
+  }
+  return normalizeProtectedSection(lines.join('\n'));
+}
+
+function normalizeProtectedSection(value = '') {
+  return normalizeMarkdownLineEndings(value).split('\n').map((line) => line.replace(/[ \t]+$/g, '')).join('\n').trim();
+}
+
+function normalizeMarkdownLineEndings(value = '') { return String(value || '').replace(/\r\n?/g, '\n'); }
+
+function recordContext(state = {}, workspaceId = '', recordId = '') {
+  const targetId = String(workspaceId || state?.activeWorkspaceId || '');
+  const workspace = (state?.workspaces || []).find((item) => String(item?.id || '') === targetId);
+  if (!workspace) return { ok: false, error: 'workspace.not.found', notice: 'Workspace was not found.' };
+  const cleanId = String(recordId || '').trim();
+  const record = (workspace.records || []).find((item) => String(item?.id || '') === cleanId);
+  if (!record) return { ok: false, error: 'record.not.found', notice: 'Local draft was not found.' };
+  return { ok: true, workspace, record };
+}
+
+function refusal(error, state, notice, authority = null) { return { ok: false, error, state, notice, authority }; }