@tiinex/app 0.1.1

package/src/workspaces/workspace.entrypointViewIntent.js

@@ -0,0 +1,83 @@
+import { normalizeWorkspaceDisplayOptions } from './workspace.displayOptions.js';
+
+const SUPPORTED_VIEWS = new Set(['feed', 'tree', 'lineage', 'audit']);
+
+export function workspaceEntrypointViewIntent(entrypoint = {}) {
+  const rawView = token(entrypoint.defaultView).toLowerCase();
+  const rawFilter = token(entrypoint.defaultFilter || entrypoint.filter);
+  const rawSearch = token(entrypoint.defaultSearch || entrypoint.search);
+  const selectedPath = canonicalPath(entrypoint.selectedPath);
+  const findings = [];
+  const view = rawView && SUPPORTED_VIEWS.has(rawView) ? rawView : '';
+  if (rawView && !view) findings.push(`unsupported-default-view:${rawView}`);
+  return Object.freeze({
+    schema: 'tiinex.workspace.entrypoint-view-intent.v1',
+    state: findings.length ? 'degraded' : 'qualified',
+    workspaceVerse: view,
+    defaultFilter: rawFilter,
+    query: rawSearch,
+    selectedPath,
+    findings: Object.freeze(findings)
+  });
+}
+
+export function stateWithWorkspaceEntrypointViewIntent(state = {}, workspaceId = '', entrypoint = {}) {
+  const id = token(workspaceId || state.activeWorkspaceId);
+  if (!id) return state;
+  const workspace = (Array.isArray(state.workspaces) ? state.workspaces : []).find((item) => token(item?.id) === id);
+  if (!workspace) return state;
+  const intent = workspaceEntrypointViewIntent(entrypoint);
+  if (!intent.workspaceVerse && !intent.defaultFilter && !intent.query && !intent.selectedPath && !intent.findings.length) return state;
+  const views = Object.assign({}, state.workspaceViews || {});
+  const current = Object.assign({}, views[id] || (id === state.activeWorkspaceId ? state.view : {}) || {});
+  const patch = {};
+  if (intent.workspaceVerse) patch.workspaceVerse = intent.workspaceVerse;
+  if (Object.prototype.hasOwnProperty.call(entrypoint, 'defaultSearch') || Object.prototype.hasOwnProperty.call(entrypoint, 'search')) patch.query = intent.query;
+  if (intent.defaultFilter) {
+    const displayOptions = Object.assign({}, normalizeWorkspaceDisplayOptions(current.displayOptions || {}));
+    if (intent.defaultFilter.toLowerCase() === 'all') {
+      Object.assign(displayOptions, { leavesOnly: false, showSupportingMarkdown: true, showWorkspaceArtifacts: true, showAssets: true, schemaFilter: 'all', artifactFilter: 'all', sourceFilter: 'all', mismatchesOnly: false });
+      patch.entrypointSchemaFilter = '';
+    } else {
+      Object.assign(displayOptions, { leavesOnly: false, showSupportingMarkdown: true, showWorkspaceArtifacts: true, schemaFilter: intent.defaultFilter });
+      patch.entrypointSchemaFilter = intent.defaultFilter;
+    }
+    patch.displayOptions = displayOptions;
+  }
+  if (intent.selectedPath) patch.entrypointSelectedPath = intent.selectedPath;
+  const nextView = Object.assign({}, current, patch);
+  views[id] = nextView;
+  const workspaces = (state.workspaces || []).map((item) => item.id === id ? Object.assign({}, item, { workspaceEntrypointViewIntent: intent }) : item);
+  return Object.assign({}, state, { workspaces, workspaceViews: views, view: id === state.activeWorkspaceId ? nextView : state.view });
+}
+
+export function resolveWorkspaceEntrypointViewIntent(view = {}, workspace = null) {
+  const next = Object.assign({}, view || {});
+  const records = Array.isArray(workspace?.records) ? workspace.records : [];
+  const selectedPath = canonicalPath(next.entrypointSelectedPath);
+  if (selectedPath) {
+    const matches = records.filter((record) => canonicalPath(record.path || record.sourcePath || record.sourceTarget?.sourceArtifactPath || '') === selectedPath);
+    if (matches.length === 1) {
+      next.workspaceVerse = 'lineage';
+      next.selectedRecordId = matches[0].id || '';
+      delete next.entrypointSelectedPath;
+    }
+  }
+  const requestedSchema = token(next.entrypointSchemaFilter);
+  if (requestedSchema && records.length) {
+    const matched = records.some((record) => token(record.schemaId || record.currentSchemaId || record.envelopeSchemaId) === requestedSchema);
+    next.displayOptions = Object.assign({}, next.displayOptions || {}, { schemaFilter: matched ? requestedSchema : 'all' });
+    delete next.entrypointSchemaFilter;
+  }
+  return next;
+}
+
+function canonicalPath(value = '') {
+  const out = [];
+  for (const part of String(value || '').trim().replace(/\\/g, '/').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop(); else out.push(part);
+  }
+  return out.join('/');
+}
+function token(value = '') { return String(value ?? '').trim(); }

package/src/workspaces/workspace.entrypoints.js

@@ -0,0 +1,157 @@
+import { normalizeExplicitFileRefs } from '@tiinex/core/sources/source.explicitTargets.js';
+
+export function workspaceSourceInputsFromMarkdown(markdown = '', parseWorkspaceConfig = null) {
+  return workspaceDeclaredSourceInputsFromMarkdown(markdown, parseWorkspaceConfig).filter((sourceInput) => workspaceEntrypointApplies(sourceInput.workspaceEntrypoint));
+}
+
+export function workspaceDeclaredSourceInputsFromMarkdown(markdown = '', parseWorkspaceConfig = null) {
+  if (typeof parseWorkspaceConfig !== 'function') return [];
+  let config = null;
+  try { config = parseWorkspaceConfig(markdown); } catch (_) { return []; }
+  const entrypoints = Array.isArray(config?.workspaceEntrypoints) ? config.workspaceEntrypoints : [];
+  return entrypoints.map((entrypoint) => workspaceSourceInputFromDeclaredEntrypoint(entrypoint)).filter(Boolean);
+}
+
+export function workspaceEntrypointApplies(entrypoint = {}) {
+  const value = entrypoint?.openOnApply;
+  if (typeof value === 'boolean') return value;
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) return true;
+  if (['no', 'false', 'disabled', 'disable', 'off', '0'].includes(text)) return false;
+  if (['yes', 'true', 'enabled', 'enable', 'on', '1'].includes(text)) return true;
+  return true;
+}
+
+export function workspaceSourceInputFromEntrypoint(entrypoint = {}) {
+  if (!workspaceEntrypointApplies(entrypoint)) return null;
+  return workspaceSourceInputFromDeclaredEntrypoint(entrypoint);
+}
+
+export function workspaceSourceInputFromDeclaredEntrypoint(entrypoint = {}) {
+  const repository = String(entrypoint?.repository || entrypoint?.repo || '').trim();
+  if (!repository) return null;
+  const issueUrls = entrypoint.issueUrl || entrypoint.issueUrls || '';
+  return {
+    repository,
+    ref: entrypoint.ref || '',
+    rootPath: entrypoint.rootPath || '.topics',
+    label: entrypoint.workspaceLabel || entrypoint.name || entrypoint.label || repository,
+    sourceKind: entrypoint.sourceKind || entrypoint.kind || 'github-tree',
+    repoDiscovery: truthyWorkspaceConfigValue(entrypoint.repoFilesDiscovery ?? entrypoint.repoDiscovery ?? true),
+    issueDiscovery: truthyWorkspaceConfigValue(entrypoint.issueDiscovery ?? entrypoint.issueSnapshots ?? false),
+    issueUrls,
+    explicitFileRefs: entrypoint.explicitFileRefs || entrypoint.fileRefs || '',
+    fileRefs: entrypoint.explicitFileRefs || entrypoint.fileRefs || '',
+    preserveView: true,
+    allowSourceCache: true,
+    workspaceEntrypoint: Object.assign({}, entrypoint)
+  };
+}
+
+export function addConfiguredSourceToWorkspace(lifecycle, state, workspaceId, sourceInput, overrides = {}) {
+  return lifecycle?.addWorkspaceSource?.(state, workspaceId, Object.assign({
+    repository: sourceInput.repository,
+    repo: sourceInput.repository,
+    ref: sourceInput.ref || '',
+    rootPath: sourceInput.rootPath || '.topics',
+    label: sourceInput.label || sourceInput.repository,
+    sourceKind: sourceInput.sourceKind || 'github-tree',
+    repoDiscovery: Boolean(sourceInput.repoDiscovery),
+    issueDiscovery: Boolean(sourceInput.issueDiscovery),
+    issueUrls: sourceInput.issueUrls || '',
+    explicitFileRefs: sourceInput.explicitFileRefs || sourceInput.fileRefs || [],
+    workspaceMatch: sourceInput.workspaceMatch || '',
+    appConfigPlan: sourceInput.appConfigPlan || '',
+    openBehavior: sourceInput.openBehavior || '',
+    preferredDisplay: sourceInput.preferredDisplay || '',
+    discoveryState: 'deferred'
+  }, overrides));
+}
+
+export function sourceMaterializationCompleteEnough(source = {}, sourceInput = {}) {
+  const state = String(source.discoveryState || '').toLowerCase();
+  if (!['loaded', 'partial'].includes(state)) return false;
+  const explicitFileRefs = normalizeExplicitFileRefs(sourceInput.explicitFileRefs ?? sourceInput.fileRefs ?? sourceInput.config?.explicitFileRefs ?? []);
+  const wantsRepo = Boolean(sourceInput.repoDiscovery);
+  const wantsIssues = Boolean(sourceInput.issueDiscovery || sourceInput.issueUrls);
+  if (!wantsRepo && !wantsIssues && !explicitFileRefs.length) return true;
+
+  if (explicitFileRefs.length && !explicitFilesComplete(source, explicitFileRefs.length)) return false;
+  const mixedPlan = Number(Boolean(wantsRepo)) + Number(Boolean(wantsIssues)) + Number(Boolean(explicitFileRefs.length)) > 1;
+  if (wantsRepo && !surfaceHandled(source, 'repoFiles', { allowCountFallback: !mixedPlan })) return false;
+  if (wantsIssues && !surfaceHandled(source, 'issueSnapshots', { allowCountFallback: !mixedPlan })) return false;
+  return true;
+}
+
+function explicitFilesComplete(source = {}, requestedCount = 0) {
+  const explicitSurface = source.surfaces?.explicitFiles ?? source.requestedSurfaces?.explicitFiles;
+  if (explicitSurface && typeof explicitSurface === 'object') return Number(explicitSurface.loaded || 0) >= requestedCount;
+  return Number(source.count || 0) >= requestedCount;
+}
+
+function surfaceHandled(source = {}, surfaceName = '', { allowCountFallback = false } = {}) {
+  const surface = source.surfaces?.[surfaceName] ?? source.requestedSurfaces?.[surfaceName];
+  if (surface && typeof surface === 'object') {
+    return Boolean(
+      surface.attempted === true
+      || Number(surface.loaded || 0) > 0
+      || Number(surface.discovered || 0) > 0
+      || Number(surface.failed || 0) > 0
+      || surface.skipped === true
+      || surface.unavailable === true
+    );
+  }
+  return allowCountFallback && Number(source.count || 0) > 0;
+}
+
+export function findWorkspaceForIncomingSource(state = {}, sourceInput = {}) {
+  const label = String(sourceInput.label || '').trim().toLowerCase();
+  const workspaces = Array.isArray(state?.workspaces) ? state.workspaces : [];
+  if (label) {
+    const byLabel = workspaces.find((workspace) => String(workspace?.title || workspace?.name || '').trim().toLowerCase() === label);
+    if (byLabel) return byLabel;
+    return null;
+  }
+  const signature = sourceSignature(sourceInput);
+  if (!signature) return null;
+  return workspaces.find((workspace) => (Array.isArray(workspace?.sources) ? workspace.sources : []).some((source) => sourceSignature(source) === signature)) || null;
+}
+
+export function findConfiguredSource(workspace = {}, sourceInput = {}) {
+  const signature = sourceSignature(sourceInput);
+  return (Array.isArray(workspace?.sources) ? workspace.sources : []).find((source) => sourceSignature(source) === signature) || null;
+}
+
+export function sourceSignature(source = {}) {
+  const repo = String(source.repository || source.repo || source.config?.repo || '').trim().toLowerCase();
+  if (!repo) return '';
+  const ref = String(source.ref || source.requestedRef || source.config?.ref || '').trim();
+  const root = canonicalizeLocalPath(source.rootPath || source.config?.rootPath || '.topics');
+  const repoDiscovery = Boolean(source.repoDiscovery);
+  const issueDiscovery = Boolean(source.issueDiscovery);
+  const issueUrls = normalizeIssueUrls(source.issueUrls || source.config?.issueUrls || '');
+  const explicitFileRefs = normalizeExplicitFileRefs(source.explicitFileRefs ?? source.fileRefs ?? source.config?.explicitFileRefs ?? source.config?.fileRefs ?? []).slice().sort().join('\n');
+  return [repo, ref, root, repoDiscovery ? 'repo:on' : 'repo:off', issueDiscovery ? 'issues:on' : 'issues:off', issueUrls, explicitFileRefs].join('|');
+}
+
+export function canonicalizeLocalPath(inputPath = '') {
+  let p = String(inputPath || '').trim().replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+  const out = [];
+  for (const part of p.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}
+
+function normalizeIssueUrls(value = '') {
+  return Array.from(new Set(String(value || '').split(/\r?\n/).map((item) => item.trim()).filter(Boolean))).sort().join('\n');
+}
+
+function truthyWorkspaceConfigValue(value) {
+  if (typeof value === 'boolean') return value;
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) return false;
+  return !['off', 'false', 'no', '0', 'disabled'].includes(text);
+}

package/src/workspaces/workspace.feedSort.js

@@ -0,0 +1,152 @@
+export function sortWorkspaceFeedRecords(records = []) {
+  const list = Array.isArray(records) ? records.slice() : [];
+  return list.sort(compareWorkspaceFeedRecords);
+}
+
+export function compareWorkspaceFeedRecords(a = {}, b = {}) {
+  const timeDelta = workspaceRecordSortTimestamp(b) - workspaceRecordSortTimestamp(a);
+  if (timeDelta) return timeDelta;
+  const issueSequenceDelta = issuePublicationSequence(b) - issuePublicationSequence(a);
+  if (issueSequenceDelta) return issueSequenceDelta;
+  const pathDelta = normalizedRecordPath(a).localeCompare(normalizedRecordPath(b), undefined, { numeric: true, sensitivity: 'base' });
+  if (pathDelta) return pathDelta;
+  return String(a.id || '').localeCompare(String(b.id || ''), undefined, { numeric: true, sensitivity: 'base' });
+}
+
+export function workspaceRecordSortTimestamp(record = {}) {
+  const createdAt = record.currentCreatedAt || record.createdAt || record.date || '';
+  const createdTime = sortableDate(createdAt);
+  const issueSourceTime = issueSourceSortTimestamp(record);
+  if (issueSourceTime) {
+    if (!isEmbeddedIssueArtifact(record)) return issueSourceTime;
+    if (!createdTime) return issueSourceTime;
+    const sourceDay = utcDatePartFromTimestamp(issueSourceTime);
+    const createdDay = utcDatePartFromTimestamp(createdTime);
+    return sourceDay && createdDay && sourceDay === createdDay ? issueSourceTime : createdTime;
+  }
+  const midnightDate = createdAtMidnightDate(createdAt);
+  const committedAt = record.gitCommittedAt
+    || record.committedAt
+    || record.sourceTarget?.gitCommittedAt
+    || record.sourceTarget?.committedAt
+    || record.file?.gitCommittedAt
+    || record.file?.committedAt
+    || '';
+  if (!midnightDate || !committedAt) return createdTime;
+  if (utcDatePart(committedAt) !== midnightDate) return createdTime;
+  return sortableDate(committedAt) || createdTime;
+}
+
+function issueSourceSortTimestamp(record = {}) {
+  if (!hasIssuePublicationIdentity(record) && String(record?.sourceTarget?.surface || '') !== 'issueSnapshots') return 0;
+  return sortableDate(record.sourceTarget?.sourceSortAt || record.sourceTarget?.sourceUpdatedAt || record.snapshot?.sourceSortAt || record.snapshot?.sourceUpdatedAt || '');
+}
+
+function issuePublicationSequence(record = {}) {
+  const values = [
+    record.recoveredFromUrl,
+    record.sourceTarget?.inputTarget,
+    record.sourceTarget?.rawUrl,
+    record.sourceTarget?.browseUrl,
+    record.snapshot?.sourceUrl,
+    record.snapshot?.target?.canonicalUrl,
+    record.path,
+    record.sourceTarget?.sourceArtifactPath,
+    record.snapshot?.sourceArtifactPath
+  ];
+  if (String(record?.sourceTarget?.surface || '') !== 'issueSnapshots' && !values.some((value) => githubIssueCommentIdFromValue(value) || githubIssueNumberFromValue(value))) return 0;
+  for (const value of values) {
+    const commentId = githubIssueCommentIdFromValue(value);
+    if (commentId) return commentId;
+  }
+  for (const value of values) {
+    const issueNumber = githubIssueNumberFromValue(value);
+    if (issueNumber) return issueNumber;
+  }
+  return 0;
+}
+
+
+function isEmbeddedIssueArtifact(record = {}) {
+  const mode = String(record.sourceMode || record.recoveryKind || '').toLowerCase();
+  const targetKind = String(record.sourceTarget?.targetKind || '').toLowerCase();
+  if (record.snapshot?.embedded === true) return true;
+  if (mode.includes('embedded-artifact')) return true;
+  if (targetKind.includes('embedded-artifact')) return true;
+  return false;
+}
+
+function utcDatePartFromTimestamp(value = 0) {
+  const t = Number(value || 0);
+  if (!Number.isFinite(t) || t <= 0) return '';
+  return new Date(t).toISOString().slice(0, 10);
+}
+
+function hasIssuePublicationIdentity(record = {}) {
+  const values = [
+    record.recoveredFromUrl,
+    record.sourceTarget?.inputTarget,
+    record.sourceTarget?.rawUrl,
+    record.sourceTarget?.browseUrl,
+    record.snapshot?.sourceUrl,
+    record.snapshot?.target?.canonicalUrl,
+    record.path,
+    record.sourceTarget?.sourceArtifactPath,
+    record.snapshot?.sourceArtifactPath
+  ];
+  return values.some((value) => githubIssueCommentIdFromValue(value) || githubIssueNumberFromValue(value));
+}
+
+function githubIssueCommentIdFromValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return 0;
+  const direct = raw.match(/(?:issuecomment-|issues\/comments\/|comment-(?:\d+-)?)(\d{4,})/i)?.[1] || '';
+  if (direct) return Number(direct) || 0;
+  try {
+    const url = new URL(raw);
+    return Number(url.hash.match(/issuecomment-(\d+)/i)?.[1] || 0) || 0;
+  } catch (_) {}
+  return 0;
+}
+
+function githubIssueNumberFromValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return 0;
+  try {
+    const url = new URL(raw);
+    const parts = url.pathname.split('/').filter(Boolean);
+    const issueIndex = parts.findIndex((part) => part === 'issues');
+    const number = issueIndex >= 0 ? Number(parts[issueIndex + 1] || 0) : 0;
+    return Number.isFinite(number) ? number : 0;
+  } catch (_) {}
+  const pathParts = raw.replace(/\\/g, '/').split('/').filter(Boolean);
+  const issueIndex = pathParts.findIndex((part) => part.toLowerCase() === 'issues');
+  const number = issueIndex >= 0 ? Number(pathParts[issueIndex + 1] || 0) : 0;
+  return Number.isFinite(number) ? number : 0;
+}
+
+function sortableDate(value = '') {
+  const s = String(value || '').trim();
+  if (!s || /^unknown/i.test(s)) return 0;
+  const hasZone = /(?:z|[+-]\d{2}:?\d{2})$/i.test(s);
+  const iso = hasZone ? s : `${s.replace(' ', 'T')}Z`;
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? t : 0;
+}
+
+function createdAtMidnightDate(value = '') {
+  const s = String(value || '').trim();
+  const match = s.match(/^(\d{4}-\d{2}-\d{2})(?:[ T]00:00:00(?:\.000)?(?:Z)?)?$/i);
+  if (!match) return '';
+  return match[1];
+}
+
+function utcDatePart(value = '') {
+  const t = sortableDate(value);
+  if (!t) return '';
+  return new Date(t).toISOString().slice(0, 10);
+}
+
+function normalizedRecordPath(record = {}) {
+  return String(record.path || record.title || record.name || '').trim();
+}

package/src/workspaces/workspace.import.js

@@ -0,0 +1,212 @@
+import { upsertOriginReferenceSources } from '@tiinex/core/sources/origin.references.js';
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { resolveLocalImportConflicts } from './workspace.importConflicts.js';
+export function ensureWorkspaceForLocalMaterial(lifecycle, state, workspaceId = '', input = {}, options = {}) {
+  const current = lifecycle?.cloneState?.(state) || state;
+  const targetId = workspaceId || current?.activeWorkspaceId || '';
+  const existing = targetId && Array.isArray(current?.workspaces)
+    ? current.workspaces.find((item) => item.id === targetId)
+    : null;
+  if (existing) return { ok: true, created: false, workspace: existing, workspaceId: existing.id, state: current };
+
+  const name = normalizeWorkspaceName(lifecycle, input.name || input.title || 'Local import');
+  if (!name) return { ok: false, error: 'workspace.name.required', state };
+  const created = lifecycle?.createWorkspace?.(current, { name }, options);
+  if (!created?.ok) return created || { ok: false, error: 'workspace.create.failed', state };
+  created.workspace.importLog = Array.isArray(created.workspace.importLog) ? created.workspace.importLog : [];
+  created.workspace.importLog.unshift({
+    kind: 'workspace-auto-created-for-local-import',
+    title: name,
+    at: nowIso(options)
+  });
+  return { ok: true, created: true, workspace: created.workspace, workspaceId: created.workspace.id, state: created.state };
+}
+
+export function summarizeAdapterImportResult(adapterResult = {}, applied = {}) {
+  const records = Number(applied.addedRecords || 0);
+  const assets = Number(applied.addedAssets || 0);
+  const workspaceEntries = Number(applied.workspaceEntries || 0);
+  const warnings = Array.isArray(adapterResult.warnings) ? adapterResult.warnings : [];
+  const errors = Array.isArray(adapterResult.errors) ? adapterResult.errors : [];
+  const diagnostics = adapterResult.diagnostics || {};
+  const parts = [];
+  if (applied.workspaceOpened) parts.push('opened workspace');
+  else if (workspaceEntries) parts.push(`${workspaceEntries} workspace artifact${workspaceEntries === 1 ? '' : 's'}`);
+  if (records) parts.push(`${records} artifact${records === 1 ? '' : 's'}`);
+  if (assets) parts.push(`${assets} asset${assets === 1 ? '' : 's'}`);
+  const ok = Boolean(records || assets || applied.workspaceOpened || workspaceEntries);
+  return {
+    schema: 'tiinex.workspace.import.result.v1',
+    ok,
+    message: `${parts.length ? `Imported ${parts.join(' · ')}` : 'Import completed'}${warnings.length || errors.length ? `; ${warnings.length + errors.length} warning/error${warnings.length + errors.length === 1 ? '' : 's'}` : ''}.`,
+    counts: {
+      records,
+      assets,
+      workspaceEntries,
+      warnings: warnings.length,
+      errors: errors.length,
+      previewOmitted: Number(diagnostics.previewOmittedCount || 0)
+    },
+    warnings,
+    errors,
+    diagnostics
+  };
+}
+
+export function applyLocalAdapterResultToWorkspace(lifecycle, state, workspaceId = '', adapterResult = {}, options = {}) {
+  if (!lifecycle) return { ok: false, error: 'lifecycle.missing', state, summary: summarizeAdapterImportResult(adapterResult) };
+  let nextState = lifecycle.cloneState?.(state) || state;
+  let addedRecords = 0;
+  let addedAssets = 0;
+  let workspaceOpened = false;
+  const targetWorkspaceId = workspaceId || nextState?.activeWorkspaceId || '';
+  const diagnostics = Object.assign({}, adapterResult.diagnostics || {});
+
+  if (targetWorkspaceId) {
+    const targetWorkspace = findWorkspace(nextState, targetWorkspaceId, lifecycle);
+    const conflictResolution = resolveLocalImportConflicts(targetWorkspace || {}, adapterResult, options.conflictResolution || '');
+    if (conflictResolution.requiresResolution) {
+      return { ok: false, error: 'import.conflict.requires-resolution', state, conflicts: conflictResolution.conflicts, adapterResult, summary: summarizeAdapterImportResult(adapterResult) };
+    }
+    if (conflictResolution.cancelled) {
+      return { ok: false, error: 'import.cancelled', cancelled: true, state, conflicts: conflictResolution.conflicts, adapterResult, summary: summarizeAdapterImportResult(adapterResult) };
+    }
+    if (conflictResolution.adapterResult) {
+      adapterResult = conflictResolution.adapterResult;
+      diagnostics.importConflictResolution = conflictResolution.resolution;
+      diagnostics.importConflictCount = conflictResolution.conflicts.length;
+    }
+  }
+
+  let workspaces = Array.isArray(adapterResult.workspaceEntries) ? adapterResult.workspaceEntries : [];
+  const records = Array.isArray(adapterResult.records) ? adapterResult.records : [];
+  const assets = Array.isArray(adapterResult.assets) ? adapterResult.assets : [];
+  const hasMaterial = Boolean(records.length || assets.length || workspaces.length);
+
+  if (targetWorkspaceId && options.conflictResolution === 'replace' && workspaces.length) {
+    const targetWorkspace = findWorkspace(nextState, targetWorkspaceId, lifecycle);
+    const rootPath = canonicalImportPath(targetWorkspace?.workspaceImport?.path || '');
+    const replacement = rootPath ? workspaces.find((entry) => canonicalImportPath(entry.path || '') === rootPath) : null;
+    if (replacement && targetWorkspace) {
+      targetWorkspace.workspaceMarkdown = String(replacement.markdown || '');
+      targetWorkspace.workspaceImport = Object.assign({}, targetWorkspace.workspaceImport || {}, {
+        path: replacement.path || targetWorkspace.workspaceImport?.path || '',
+        sourceMode: replacement.sourceMode || 'local-workspace-file',
+        boundary: replacement.boundary || 'browser-local workspace file; no GitHub provenance inferred',
+        replacedAt: nowIso(options)
+      });
+      workspaces = workspaces.filter((entry) => entry !== replacement);
+      diagnostics.workspaceRootReplaced = true;
+    }
+  }
+
+  let workspaceArtifactRecords = [];
+  if (workspaces.length && !targetWorkspaceId && typeof lifecycle.openWorkspaceFromMarkdown === 'function') {
+    const first = workspaces[0];
+    const opened = lifecycle.openWorkspaceFromMarkdown(nextState, first.markdown || '', first, options);
+    if (opened?.ok) {
+      nextState = opened.state;
+      workspaceOpened = true;
+      workspaceArtifactRecords = workspaces.slice(1).map(workspaceArtifactRecordFromEntry);
+    }
+  } else if (workspaces.length) {
+    workspaceArtifactRecords = workspaces.map(workspaceArtifactRecordFromEntry);
+  }
+
+  let finalWorkspaceId = lifecycle.activeWorkspace?.(nextState)?.id || targetWorkspaceId;
+  if (!finalWorkspaceId && hasMaterial) {
+    const ensured = ensureWorkspaceForLocalMaterial(lifecycle, nextState, '', {
+      name: diagnostics.suggestedWorkspaceName || options.workspaceName || 'Local import'
+    }, options);
+    if (ensured?.ok) {
+      nextState = ensured.state;
+      finalWorkspaceId = ensured.workspaceId;
+      workspaceOpened = Boolean(ensured.created);
+    }
+  }
+
+  const canonicalRecords = records.concat(workspaceArtifactRecords);
+  if (canonicalRecords.length && finalWorkspaceId && typeof lifecycle.addWorkspaceRecords === 'function') {
+    const added = lifecycle.addWorkspaceRecords(nextState, finalWorkspaceId, canonicalRecords, options);
+    if (added?.ok) {
+      nextState = added.state;
+      addedRecords = added.records.length;
+      const workspace = findWorkspace(nextState, finalWorkspaceId, lifecycle);
+      const originSources = upsertOriginReferenceSources(workspace, added.records || []);
+      if (originSources.length) {
+        diagnostics.originReferenceSourceCount = originSources.length;
+        diagnostics.originReferenceSources = originSources.map((source) => ({ id: source.id, repo: source.repo, sourceKind: source.sourceKind }));
+      }
+    }
+  }
+  if (assets.length && finalWorkspaceId && typeof lifecycle.addWorkspaceAssets === 'function') {
+    const added = lifecycle.addWorkspaceAssets(nextState, finalWorkspaceId, assets, options);
+    if (added?.ok) {
+      nextState = added.state;
+      addedAssets = added.assets.length;
+    }
+  }
+
+  const applied = { addedRecords, addedAssets, workspaceOpened, workspaceEntries: workspaces.length, workspaceArtifacts: workspaceArtifactRecords.length };
+  const summaryInput = Object.assign({}, adapterResult, { diagnostics });
+  const summary = summarizeAdapterImportResult(summaryInput, applied);
+  nextState = appendImportSummary(lifecycle, nextState, summary, options);
+
+  return { ok: summary.ok, state: nextState, summary, workspaceId: lifecycle.activeWorkspace?.(nextState)?.id || finalWorkspaceId, ...applied };
+}
+
+export function appendImportSummary(lifecycle, state, summary, options = {}) {
+  const next = lifecycle?.cloneState?.(state) || state;
+  const workspace = lifecycle?.activeWorkspace?.(next);
+  if (!workspace) return next;
+  const entry = {
+    schema: 'tiinex.workspace.import.result.v1',
+    ok: summary.ok !== false,
+    message: String(summary.message || 'Import completed.').slice(0, 500),
+    counts: Object.assign({ records: 0, assets: 0, workspaceEntries: 0, warnings: 0, errors: 0 }, summary.counts || {}),
+    warnings: Array.isArray(summary.warnings) ? summary.warnings.slice(0, 20) : [],
+    errors: Array.isArray(summary.errors) ? summary.errors.slice(0, 20) : [],
+    diagnostics: Object.assign({}, summary.diagnostics || {}),
+    at: nowIso(options)
+  };
+  workspace.importResults = Array.isArray(workspace.importResults) ? workspace.importResults.slice() : [];
+  workspace.importResults.unshift(entry);
+  workspace.importLog = Array.isArray(workspace.importLog) ? workspace.importLog.slice() : [];
+  workspace.importLog.unshift({ kind: 'adapter-import-result', ok: entry.ok, counts: entry.counts, at: entry.at });
+  return next;
+}
+
+function workspaceArtifactRecordFromEntry(entry = {}) {
+  const path = entry.path || 'workspace.workspace.md';
+  const record = createRecordFromMarkdown(entry.markdown || '', {
+    path,
+    name: entry.title || path,
+    sourceMode: entry.sourceMode || 'archive-local-workspace-artifact'
+  });
+  return Object.assign({}, record, {
+    title: entry.title || record.title,
+    workspaceArtifactRole: {
+      schema: 'tiinex.workspace.artifact.role.v1',
+      openEligible: true,
+      mergeEligible: true,
+      origin: 'local-import'
+    },
+    importBoundary: entry.boundary || 'browser-local workspace artifact; canonical artifact record with workspace capability'
+  });
+}
+
+function canonicalImportPath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/').trim(); }
+
+function findWorkspace(state = {}, workspaceId = '', lifecycle = {}) {
+  const id = String(workspaceId || '').trim();
+  return (Array.isArray(state.workspaces) ? state.workspaces : []).find((workspace) => workspace.id === id) || lifecycle?.activeWorkspace?.(state) || null;
+}
+
+function normalizeWorkspaceName(lifecycle, value) {
+  if (typeof lifecycle?.normalizeWorkspaceName === 'function') return lifecycle.normalizeWorkspaceName(value);
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, 72);
+}
+
+function nowIso(options = {}) {
+  return typeof options.clock === 'function' ? options.clock() : new Date().toISOString();
+}