@tiinex/app 0.1.1

package/src/workspaces/workspace.discoveryView.js

@@ -0,0 +1,386 @@
+import { resolveLineage } from '@tiinex/core/lineage/lineage.resolve.js';
+import { LineageEdgeKind, LineageResolutionStatus } from '@tiinex/core/lineage/lineage.model.js';
+import { inferRecordMaterialRole, isDiscoveryWorkLeafEligible, isSupportingRecord, sourceBoundaryClass, MaterialRole } from '@tiinex/core/workspaces/workspace.materialRole.js';
+import { sortWorkspaceFeedRecords } from './workspace.feedSort.js';
+import { normalizeWorkspaceDisplayOptions, normalizeDisplayFilterValue } from './workspace.displayOptions.js';
+import { auditIsMismatch, recordSchemaValue, recordMatchesQuery, assetMatchesQuery } from './workspace.displayFilters.js';
+import { isLocalShadowedBySourceRecord } from './workspace.materialReconciliation.js';
+
+export function buildWorkspaceDiscoveryView(workspace = {}, options = {}) {
+  const records = Array.isArray(options.records) ? options.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const assets = Array.isArray(options.assets) ? options.assets : (Array.isArray(workspace.assets) ? workspace.assets : []);
+  const displayOptions = normalizeWorkspaceDisplayOptions(options.displayOptions || {});
+  const query = String(options.query || '').trim();
+  const auditById = options.auditById instanceof Map ? options.auditById : new Map();
+  const materialIndex = options.materialIndex && Array.isArray(options.materialIndex.records) && options.materialIndex.records === records
+    ? options.materialIndex
+    : buildDiscoveryMaterialIndex(records);
+  const hiddenReasonsById = new Map();
+  const hiddenReasonsByRecordId = new Map();
+  const membershipById = new Map();
+  const membershipByRecordId = new Map();
+
+  const visibleRecords = sortWorkspaceFeedRecords(records.filter((record) => {
+    const inclusion = discoveryRecordMembership(record, displayOptions, auditById, materialIndex, query);
+    membershipByRecordId.set(String(record?.id || record?.path || ''), inclusion);
+    if (!inclusion.visible) hiddenReasonsByRecordId.set(String(record?.id || record?.path || ''), inclusion.reason);
+    for (const key of descriptorFor(record, materialIndex)?.keys || recordKeys(record)) {
+      membershipById.set(key, inclusion);
+      if (!inclusion.visible) hiddenReasonsById.set(key, inclusion.reason);
+    }
+    return inclusion.visible;
+  }));
+
+  const visibleAssets = displayOptions.showAssets ? assets.filter((asset) => assetMatchesQuery(asset, query)) : [];
+  const projectedRecords = visibleRecords;
+  const visibleWorkspaceArtifactCount = projectedRecords.filter((record) => inferRecordMaterialRole(record) === MaterialRole.workspaceArtifact).length;
+  const workspaceArtifactCount = records.filter((record) => inferRecordMaterialRole(record) === MaterialRole.workspaceArtifact).length;
+  const choices = discoveryOptionChoices(records, auditById, materialIndex);
+
+  return Object.freeze({
+    records: projectedRecords,
+    assets: visibleAssets,
+    materialIndex,
+    choices,
+    counts: Object.freeze({
+      records: records.length,
+      visibleRecords: projectedRecords.length,
+      leaves: choices.leafCount,
+      supportingMarkdown: choices.supportingCount,
+      mismatches: choices.mismatchCount,
+      assets: assets.length,
+      visibleAssets: visibleAssets.length,
+      workspaceArtifacts: workspaceArtifactCount,
+      visibleWorkspaceArtifacts: visibleWorkspaceArtifactCount,
+          }),
+    hiddenReasonsById,
+    hiddenReasonsByRecordId,
+    membershipById,
+    membershipByRecordId
+  });
+}
+
+export function discoveryRecordMembership(record = {}, options = {}, auditById = new Map(), materialIndex = null, query = '') {
+  const descriptor = descriptorFor(record, materialIndex);
+  const role = descriptor?.role || inferRecordMaterialRole(record);
+  const supporting = descriptor ? descriptor.supporting : isSupportingRecord(record);
+  const discoveryLeaf = isDiscoveryLeafRecord(record, materialIndex);
+  const workspaceArtifactRecord = role === MaterialRole.workspaceArtifact;
+  const parentReason = discoveryParentReason(record, materialIndex);
+  if (isLocalShadowedBySourceRecord(record)) return hidden('hidden-local-shadowed-by-source', role, discoveryLeaf, supporting);
+  const schemaFilter = normalizeDisplayFilterValue(options.schemaFilter);
+  const explicitSchemaMatch = schemaFilter !== 'all' && recordSchemaValue(record) === schemaFilter;
+  if (workspaceArtifactRecord && options.showWorkspaceArtifacts === false) return hidden('hidden-workspace-artifacts', role, discoveryLeaf, supporting);
+  if (options.leavesOnly && !discoveryLeaf && !explicitSchemaMatch) return hidden(parentReason || (workspaceArtifactRecord ? 'hidden-workspace-parent' : 'hidden-not-terminal-work-leaf'), role, discoveryLeaf, supporting);
+  if (!workspaceArtifactRecord && !options.showSupportingMarkdown && supporting && !explicitSchemaMatch) return hidden('hidden-supporting', role, discoveryLeaf, supporting);
+  if (options.mismatchesOnly && !auditIsMismatch(record, auditById.get(record.id))) return hidden('hidden-filter', role, discoveryLeaf, supporting);
+  if (schemaFilter !== 'all' && !explicitSchemaMatch) return hidden('hidden-filter', role, discoveryLeaf, supporting);
+  const artifactFilter = normalizeDisplayFilterValue(options.artifactFilter);
+  if (artifactFilter !== 'all' && role !== artifactFilter) return hidden('hidden-filter', role, discoveryLeaf, supporting);
+  const sourceFilter = normalizeDisplayFilterValue(options.sourceFilter);
+  const sourceClass = descriptor?.sourceClass || sourceBoundaryClass(record);
+  if (sourceFilter !== 'all' && sourceClass !== sourceFilter) return hidden('hidden-filter', role, discoveryLeaf, supporting);
+  if (!recordMatchesQuery(record, query)) return hidden('hidden-query', role, discoveryLeaf, supporting);
+  return Object.freeze({ visible: true, reason: 'visible', role, discoveryLeaf, supporting });
+}
+
+export function buildDiscoveryDisplayOptionCounts(workspace = {}, options = {}) {
+  const auditById = options.auditById instanceof Map ? options.auditById : new Map();
+  const view = buildWorkspaceDiscoveryView(workspace, {
+    records: Array.isArray(options.records) ? options.records : workspace.records,
+    assets: Array.isArray(options.assets) ? options.assets : workspace.assets,
+    displayOptions: Object.assign({}, options.displayOptions || {}, {
+      leavesOnly: false,
+      showSupportingMarkdown: true,
+      showWorkspaceArtifacts: true,
+      showAssets: true,
+      mismatchesOnly: false,
+      schemaFilter: 'all',
+      artifactFilter: 'all',
+      sourceFilter: 'all'
+    }),
+    query: '',
+    auditById
+  });
+  return Object.freeze({
+    records: view.counts.records,
+    leaves: view.counts.leaves,
+    supportingMarkdown: view.counts.supportingMarkdown,
+    mismatches: view.counts.mismatches,
+    assets: view.counts.assets,
+    workspaceArtifacts: view.counts.workspaceArtifacts,
+    schemaChoices: view.choices.schemas,
+    artifactChoices: view.choices.artifacts,
+    sourceChoices: view.choices.sources
+  });
+}
+
+export function buildDiscoveryMaterialIndex(records = []) {
+  const source = Array.isArray(records) ? records : [];
+  const recordIndex = buildDiscoveryRecordIndex(source);
+  const lineageParentKeys = new Set();
+  const lineageChildKeys = new Set();
+  const pathParentKeys = new Set();
+  const pathChildKeys = new Set();
+  const parentReasonsByKey = new Map();
+  let resolved = null;
+  try {
+    resolved = resolveLineage(source, { depth: 'discovery-membership' });
+  } catch {
+    resolved = null;
+  }
+  for (const edge of Array.isArray(resolved?.edges) ? resolved.edges : []) {
+    if (edge.kind !== LineageEdgeKind.parent) continue;
+    if (!edge.from || !edge.to) continue;
+    if (edge.status === LineageResolutionStatus.missing) continue;
+    const parent = recordIndex.byKey.get(keyLookup(edge.from));
+    const child = recordIndex.byKey.get(keyLookup(edge.to));
+    if (edge.status === LineageResolutionStatus.mismatch && !mismatchedEdgeStillOwnsDiscoveryParenthood(parent, child)) continue;
+    for (const key of parent ? parent.keys : [String(edge.from)]) {
+      lineageParentKeys.add(key);
+      parentReasonsByKey.set(key, 'hidden-loaded-parent');
+    }
+    for (const key of child ? child.keys : [String(edge.to)]) lineageChildKeys.add(key);
+  }
+
+  addPathParentMembership(recordIndex, pathParentKeys, pathChildKeys, parentReasonsByKey);
+
+  const parentKeys = unionSets(lineageParentKeys, pathParentKeys);
+  const childKeys = unionSets(lineageChildKeys, pathChildKeys);
+  return Object.freeze({
+    parentKeys,
+    childKeys,
+    parentIds: parentKeys,
+    childIds: childKeys,
+    lineageParentKeys,
+    lineageChildKeys,
+    pathParentKeys,
+    pathChildKeys,
+    parentReasonsByKey,
+    descriptors: recordIndex.descriptors,
+    records: source,
+    descriptorsByRecord: recordIndex.byRecord,
+    descriptorsByKey: recordIndex.byKey,
+    hasLineage: Boolean(resolved),
+    parentCount: parentKeys.size,
+    childCount: childKeys.size,
+    lineageParentCount: lineageParentKeys.size,
+    pathParentCount: pathParentKeys.size
+  });
+}
+
+export function isDiscoveryLeafRecord(record = {}, materialIndex = null) {
+  const descriptor = descriptorFor(record, materialIndex);
+  const workEligible = descriptor ? descriptor.workEligible : isDiscoveryWorkLeafEligible(record);
+  if (!workEligible) return false;
+  const keys = descriptor?.keys || recordKeys(record);
+  if (!materialIndex?.parentKeys) return true;
+  return !keys.some((key) => materialIndex.parentKeys.has(key));
+}
+
+export function discoveryParentReason(record = {}, materialIndex = null) {
+  const descriptor = descriptorFor(record, materialIndex);
+  const workEligible = descriptor ? descriptor.workEligible : isDiscoveryWorkLeafEligible(record);
+  if (!workEligible) {
+    const role = descriptor?.role || inferRecordMaterialRole(record);
+    if (role === MaterialRole.schemaDefinition) return 'hidden-schema-definition';
+    if (role === MaterialRole.supporting || role === MaterialRole.unknown) return 'hidden-supporting';
+    return 'hidden-not-work-leaf';
+  }
+  for (const key of descriptor?.keys || recordKeys(record)) {
+    const reason = materialIndex?.parentReasonsByKey?.get(key);
+    if (reason) return reason;
+  }
+  return '';
+}
+
+
+function hidden(reason, role, discoveryLeaf, supporting) {
+  return Object.freeze({ visible: false, reason, role, discoveryLeaf, supporting });
+}
+
+function discoveryOptionChoices(records = [], auditById = new Map(), materialIndex = null) {
+  const schemaCounts = new Map();
+  const artifactCounts = new Map();
+  const sourceCounts = new Map();
+  const items = Array.isArray(records) ? records : [];
+  for (const record of items) {
+    const descriptor = descriptorFor(record, materialIndex);
+    const schema = descriptor?.schema || recordSchemaValue(record);
+    if (schema) schemaCounts.set(schema, (schemaCounts.get(schema) || 0) + 1);
+    const artifact = descriptor?.role || inferRecordMaterialRole(record);
+    artifactCounts.set(artifact, (artifactCounts.get(artifact) || 0) + 1);
+    const sourceClass = descriptor?.sourceClass || sourceBoundaryClass(record);
+    sourceCounts.set(sourceClass, (sourceCounts.get(sourceClass) || 0) + 1);
+  }
+  const mismatchCount = items.filter((record) => auditIsMismatch(record, auditById.get(record.id))).length;
+  return Object.freeze({
+    schemas: Array.from(schemaCounts.entries()).sort((a, b) => a[0].localeCompare(b[0])),
+    artifacts: [MaterialRole.leaf, MaterialRole.schemaDefinition, MaterialRole.supporting, MaterialRole.unknown]
+      .filter((key) => artifactCounts.has(key))
+      .map((key) => [key, artifactCounts.get(key)]),
+    sources: ['source-backed', 'local', 'unknown']
+      .filter((key) => sourceCounts.has(key))
+      .map((key) => [key, sourceCounts.get(key)]),
+    supportingCount: (artifactCounts.get(MaterialRole.supporting) || 0) + (artifactCounts.get(MaterialRole.schemaDefinition) || 0) + (artifactCounts.get(MaterialRole.unknown) || 0),
+    mismatchCount,
+    leafCount: items.filter((record) => isDiscoveryLeafRecord(record, materialIndex)).length
+  });
+}
+
+function buildDiscoveryRecordIndex(records = []) {
+  const descriptors = [];
+  const byRecord = new Map();
+  const byKey = new Map();
+  const workCandidates = [];
+  const candidatesByDir = new Map();
+  const folderRootTracesByDir = new Map();
+
+  for (const record of Array.isArray(records) ? records : []) {
+    const role = inferRecordMaterialRole(record);
+    const supporting = role === MaterialRole.supporting || role === MaterialRole.schemaDefinition || role === MaterialRole.unknown;
+    const sourceClass = sourceBoundaryClass(record);
+    const path = normalizeDiscoveryPath(record.path || record.sourcePath || record.source?.path || '');
+    const dir = dirname(path);
+    const name = basename(path).toLowerCase();
+    const keys = recordKeys(record);
+    const descriptor = Object.freeze({
+      record,
+      role,
+      supporting,
+      sourceClass,
+      schema: recordSchemaValue(record),
+      path,
+      dir,
+      name,
+      keys,
+      keySet: new Set(keys),
+      workEligible: (role === MaterialRole.leaf && isDiscoveryWorkLeafEligible(record)) || role === MaterialRole.workspaceArtifact
+    });
+    descriptors.push(descriptor);
+    byRecord.set(record, descriptor);
+    for (const key of keys) if (!byKey.has(keyLookup(key))) byKey.set(keyLookup(key), descriptor);
+    if (descriptor.workEligible && descriptor.path && descriptor.dir) {
+      workCandidates.push(descriptor);
+      pushMapList(candidatesByDir, descriptor.dir, descriptor);
+      if (descriptor.name === '001.trace.md') pushMapList(folderRootTracesByDir, descriptor.dir, descriptor);
+    }
+  }
+
+  return Object.freeze({ descriptors, byRecord, byKey, workCandidates, candidatesByDir, folderRootTracesByDir });
+}
+
+
+function mismatchedEdgeStillOwnsDiscoveryParenthood(parent = null, child = null) {
+  if (!parent || !child) return false;
+  // A mismatched/stale edge between ordinary work leaves should stay visible in Discovery so
+  // users can inspect the changed parent material. Workspace/root entrypoints are containers;
+  // if a loaded child still points at them, Leaves only should not show them as terminal work.
+  return parent.role === MaterialRole.workspaceArtifact && Boolean(child.workEligible);
+}
+
+function addPathParentMembership(recordIndex, pathParentKeys, pathChildKeys, parentReasonsByKey) {
+  const candidates = Array.isArray(recordIndex?.workCandidates) ? recordIndex.workCandidates : [];
+  const byDir = recordIndex?.candidatesByDir instanceof Map ? recordIndex.candidatesByDir : new Map();
+  const rootsByDir = recordIndex?.folderRootTracesByDir instanceof Map ? recordIndex.folderRootTracesByDir : new Map();
+  for (const child of candidates) {
+    for (const ancestorDir of ancestorDirs(child.dir)) {
+      const parents = byDir.get(ancestorDir) || [];
+      for (const parent of parents) addPathParent(parent, child, pathParentKeys, pathChildKeys, parentReasonsByKey, 'hidden-path-parent');
+    }
+    for (const parent of rootsByDir.get(child.dir) || []) {
+      addPathParent(parent, child, pathParentKeys, pathChildKeys, parentReasonsByKey, 'hidden-path-parent');
+    }
+  }
+}
+
+function addPathParent(parent, child, pathParentKeys, pathChildKeys, parentReasonsByKey, reason) {
+  if (!parent || !child || sameDescriptor(parent, child)) return;
+  for (const key of parent.keys) {
+    pathParentKeys.add(key);
+    if (!parentReasonsByKey.has(key)) parentReasonsByKey.set(key, reason);
+  }
+  for (const key of child.keys) pathChildKeys.add(key);
+}
+
+function descriptorFor(record = {}, materialIndex = null) {
+  if (materialIndex?.descriptorsByRecord instanceof Map) {
+    const byRecord = materialIndex.descriptorsByRecord.get(record);
+    if (byRecord) return byRecord;
+  }
+  if (materialIndex?.descriptorsByKey instanceof Map) {
+    for (const key of recordKeys(record)) {
+      const byKey = materialIndex.descriptorsByKey.get(keyLookup(key));
+      if (byKey) return byKey;
+    }
+  }
+  return null;
+}
+
+function sameDescriptor(a = {}, b = {}) {
+  if (a.record && b.record && a.record === b.record) return true;
+  const aKeys = a.keySet || new Set(a.keys || []);
+  for (const key of b.keys || []) if (aKeys.has(key)) return true;
+  return false;
+}
+
+function recordKeys(record = {}) {
+  const keys = [record.id, record.path, record.sourcePath, record.source?.path]
+    .map((value) => String(value || '').trim())
+    .filter(Boolean);
+  const canonical = keys.map((value) => normalizeDiscoveryPath(value)).filter(Boolean);
+  return Array.from(new Set(keys.concat(canonical)));
+}
+
+function keyLookup(value = '') {
+  const raw = String(value || '').trim();
+  return normalizeDiscoveryPath(raw) || raw;
+}
+
+function unionSets(...sets) {
+  const out = new Set();
+  for (const set of sets) for (const value of set || []) out.add(value);
+  return out;
+}
+
+function pushMapList(map, key, value) {
+  const existing = map.get(key);
+  if (existing) existing.push(value);
+  else map.set(key, [value]);
+}
+
+function ancestorDirs(dir = '') {
+  const parts = normalizeDiscoveryPath(dir).split('/').filter(Boolean);
+  const out = [];
+  for (let i = 1; i < parts.length; i += 1) out.push(parts.slice(0, i).join('/'));
+  return out;
+}
+
+function normalizeDiscoveryPath(value = '') {
+  let raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    raw = url.pathname.replace(/^\/+/, '');
+  } catch {
+    // not a URL
+  }
+  const out = [];
+  for (const part of raw.replace(/\\/g, '/').replace(/[#?].*$/, '').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}
+
+function dirname(path = '') {
+  const parts = normalizeDiscoveryPath(path).split('/').filter(Boolean);
+  parts.pop();
+  return parts.join('/');
+}
+
+function basename(path = '') {
+  const parts = normalizeDiscoveryPath(path).split('/').filter(Boolean);
+  return parts[parts.length - 1] || '';
+}

package/src/workspaces/workspace.displayFilters.js

@@ -0,0 +1,63 @@
+import { inferRecordMaterialRole, isSupportingRecord, sourceBoundaryClass } from '@tiinex/core/workspaces/workspace.materialRole.js';
+import { normalizeDisplayFilterValue } from './workspace.displayOptions.js';
+
+export function isSupportingMarkdownRecord(record = {}) {
+  return isSupportingRecord(record);
+}
+
+export function recordSourceClass(record = {}) {
+  return sourceBoundaryClass(record);
+}
+
+export function recordSchemaValue(record = {}) {
+  return String(record.schemaId || record.currentSchemaId || record.envelopeSchemaId || '').trim();
+}
+
+export function qualifiedSchemaFilterValue(value = 'all', records = []) {
+  const normalized = normalizeDisplayFilterValue(value);
+  if (normalized === 'all') return 'all';
+  return (Array.isArray(records) ? records : []).some((record) => recordSchemaValue(record) === normalized) ? normalized : 'all';
+}
+
+export function recordArtifactClass(record = {}) {
+  return inferRecordMaterialRole(record);
+}
+
+export function auditIsMismatch(record = {}, auditItem = null) {
+  const status = String(auditItem?.status || '').toLowerCase();
+  return status === 'invalid-or-incomplete' || status === 'degraded' || status === 'missing' || status === 'error';
+}
+
+export function displayRecordIncluded(record = {}, options = {}, auditById = new Map()) {
+  const supporting = isSupportingMarkdownRecord(record);
+  if (options.leavesOnly && recordArtifactClass(record) !== 'leaf') return false;
+  if (!options.showSupportingMarkdown && supporting) return false;
+  if (options.mismatchesOnly && !auditIsMismatch(record, auditById.get(record.id))) return false;
+  const schemaFilter = normalizeDisplayFilterValue(options.schemaFilter);
+  if (schemaFilter !== 'all' && recordSchemaValue(record) !== schemaFilter) return false;
+  const artifactFilter = normalizeDisplayFilterValue(options.artifactFilter);
+  if (artifactFilter !== 'all' && recordArtifactClass(record) !== artifactFilter) return false;
+  const sourceFilter = normalizeDisplayFilterValue(options.sourceFilter);
+  if (sourceFilter !== 'all' && recordSourceClass(record) !== sourceFilter) return false;
+  return true;
+}
+
+export function recordMatchesQuery(record = {}, query = '') {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return true;
+  return [
+    record.title,
+    record.summary,
+    record.kind,
+    record.status,
+    record.path,
+    recordSchemaValue(record),
+    record.markdown
+  ].some((value) => String(value || '').toLowerCase().includes(q));
+}
+
+export function assetMatchesQuery(asset = {}, query = '') {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return true;
+  return [asset.name, asset.path, asset.type, asset.previewState, asset.sourceMode].some((value) => String(value || '').toLowerCase().includes(q));
+}

package/src/workspaces/workspace.displayOptions.js

@@ -0,0 +1,58 @@
+export const DEFAULT_DISPLAY_OPTIONS = Object.freeze({
+  leavesFirst: false,
+  leavesOnly: true,
+  mismatchesOnly: false,
+  showSupportingMarkdown: false,
+  showWorkspaceArtifacts: true,
+  showAssets: false,
+  schemaFilter: 'all',
+  artifactFilter: 'all',
+  sourceFilter: 'all'
+});
+
+export function normalizeWorkspaceDisplayOptions(input = {}) {
+  const source = input && typeof input === 'object' ? input : {};
+  return {
+    leavesFirst: source.leavesFirst === true,
+    leavesOnly: source.leavesOnly !== false,
+    mismatchesOnly: source.mismatchesOnly === true,
+    showSupportingMarkdown: source.showSupportingMarkdown === true ? true : DEFAULT_DISPLAY_OPTIONS.showSupportingMarkdown,
+    showWorkspaceArtifacts: source.showWorkspaceArtifacts !== false ? DEFAULT_DISPLAY_OPTIONS.showWorkspaceArtifacts : false,
+    showAssets: source.showAssets === true ? true : DEFAULT_DISPLAY_OPTIONS.showAssets,
+    schemaFilter: normalizeDisplayFilterValue(source.schemaFilter),
+    artifactFilter: normalizeDisplayFilterValue(source.artifactFilter),
+    sourceFilter: normalizeDisplayFilterValue(source.sourceFilter)
+  };
+}
+
+export function normalizeDisplayFilterValue(value) {
+  const text = String(value || 'all').trim();
+  return text || 'all';
+}
+
+export function lineageDisplayOptions(input = {}) {
+  const normalized = normalizeWorkspaceDisplayOptions(input);
+  return Object.assign({}, normalized, {
+    leavesOnly: false,
+    showSupportingMarkdown: true,
+    showWorkspaceArtifacts: true,
+    showAssets: true
+  });
+}
+
+export function displayOptionsActiveConstraintCount(options = {}, scope = 'discovery') {
+  const normalized = normalizeWorkspaceDisplayOptions(options);
+  const lineageScope = String(scope || 'discovery') === 'lineage';
+  const common = (normalized.mismatchesOnly ? 1 : 0)
+    + (normalized.schemaFilter !== 'all' ? 1 : 0)
+    + (normalized.artifactFilter !== 'all' ? 1 : 0)
+    + (normalized.sourceFilter !== 'all' ? 1 : 0);
+  if (lineageScope) return common;
+  return common
+    + (normalized.showAssets === false ? 1 : 0)
+    + (normalized.showWorkspaceArtifacts === false ? 1 : 0)
+    + (normalized.showSupportingMarkdown === false ? 1 : 0)
+    + (normalized.leavesOnly ? 1 : 0);
+}
+
+export const displayOptionsHiddenCount = displayOptionsActiveConstraintCount;

package/src/workspaces/workspace.emptyStateCopy.js

@@ -0,0 +1,24 @@
+export function workspaceEmptyStateCopy({ filtered = false, hasMaterial = false, query = '', summary = null, progress = null } = {}) {
+  const latest = summary?.latestImport || null;
+  const hasActiveProgress = Boolean(progress?.active);
+  const hasDeferredSourceReceipt = Boolean(!hasMaterial && latest && (latest.message || latest.warnings?.length || latest.errors?.length));
+  const message = filtered
+    ? 'No nodes match this view.'
+    : hasMaterial
+      ? 'No artifacts match this view.'
+      : hasActiveProgress
+        ? 'Loading workspace material…'
+        : hasDeferredSourceReceipt
+          ? 'No readable material was produced.'
+          : 'No material yet.';
+  const hint = filtered && query
+    ? `Search filter: ${query}`
+    : hasActiveProgress
+      ? String(progress.label || 'Source loading is running for this workspace.').slice(0, 260)
+      : hasDeferredSourceReceipt
+        ? String(latest.message || 'The source boundary is registered, but the selected reader did not produce records.').slice(0, 260)
+        : '';
+  const firstWarning = hasDeferredSourceReceipt && latest.warnings?.length ? latest.warnings[0] : null;
+  const firstError = hasDeferredSourceReceipt && latest.errors?.length ? latest.errors[0] : null;
+  return Object.freeze({ message, hint, firstWarning, firstError, hasActiveProgress, hasDeferredSourceReceipt });
+}

package/src/workspaces/workspace.entrypointLifecycle.js

@@ -0,0 +1,131 @@
+import { addConfiguredSourceToWorkspace, findConfiguredSource, findWorkspaceForIncomingSource, sourceMaterializationCompleteEnough, sourceSignature } from './workspace.entrypoints.js';
+import { replaceNonDraftWorkspaceSet } from './workspace.openSemantics.js';
+import { stateWithWorkspaceEntrypointViewIntent } from './workspace.entrypointViewIntent.js';
+
+export function openWorkspaceEntrypointSet({
+  lifecycle,
+  state = {},
+  sourceInputs = [],
+  entry = null,
+  workspaceInput = defaultWorkspaceInput,
+  afterCreate = null,
+  annotateWorkspace = null,
+  registerSources = true
+} = {}) {
+  const inputs = normalizeSourceInputs(sourceInputs);
+  if (!inputs.length) return { ok: false, error: 'workspace.entrypoint-set.empty', message: 'Workspace entrypoint has no openable workspace set.', state, entry, sourceInputs: [] };
+  if (!lifecycle?.createWorkspace || (registerSources && !lifecycle?.addWorkspaceSource)) return { ok: false, error: 'workspace.lifecycle.incomplete', message: 'Workspace lifecycle cannot apply workspace entrypoints.', state, entry, sourceInputs: [] };
+
+  let next = cloneLifecycleState(lifecycle, state);
+  const preparedInputs = [];
+  const openedWorkspaceIds = [];
+  for (let index = 0; index < inputs.length; index += 1) {
+    const sourceInput = inputs[index];
+    const createInput = workspaceInput(sourceInput, index, inputs) || defaultWorkspaceInput(sourceInput, index);
+    const created = lifecycle.createWorkspace(next, createInput, {});
+    if (!created?.ok) continue;
+    next = created.state;
+    if (typeof afterCreate === 'function') {
+      const adjusted = afterCreate({ state: next, workspace: created.workspace, sourceInput, index, inputs, entry });
+      if (adjusted) next = adjusted;
+    }
+    if (typeof annotateWorkspace === 'function') annotateWorkspace({ state: next, workspaceId: created.workspace.id, workspace: created.workspace, sourceInput, index, inputs, entry, mode: 'open' });
+    if (registerSources) {
+      const added = addConfiguredSourceToWorkspace(lifecycle, next, created.workspace.id, sourceInput, { discoveryState: 'deferred' });
+      if (added?.ok) {
+        next = added.state;
+        preparedInputs.push(Object.assign({}, sourceInput, { workspaceId: created.workspace.id, sourceId: added.source?.id || sourceInput.sourceId || '' }));
+      }
+    } else {
+      preparedInputs.push(Object.assign({}, sourceInput, { workspaceId: created.workspace.id, sourceId: sourceInput.sourceId || '' }));
+    }
+    openedWorkspaceIds.push(created.workspace.id);
+  }
+  if (!openedWorkspaceIds.length) return { ok: false, error: 'workspace.open.no-entrypoints', message: 'Workspace entrypoint has no usable workspace set.', state, entry, sourceInputs: [] };
+  const replaced = replaceNonDraftWorkspaceSet(next, openedWorkspaceIds);
+  next = replaced.state;
+  for (const prepared of preparedInputs) next = stateWithWorkspaceEntrypointViewIntent(next, prepared.workspaceId || '', prepared.workspaceEntrypoint || {});
+  const preferredWorkspaceId = openedWorkspaceIds[0] || '';
+  if (preferredWorkspaceId && (next.workspaces || []).some((workspace) => workspace.id === preferredWorkspaceId)) next.activeWorkspaceId = preferredWorkspaceId;
+  const workspace = (next.workspaces || []).find((item) => item.id === preferredWorkspaceId)
+    || (next.workspaces || []).find((item) => openedWorkspaceIds.includes(item.id))
+    || null;
+  return { ok: true, state: next, workspace, workspaces: openedWorkspaceIds.map((id) => (next.workspaces || []).find((item) => item.id === id)).filter(Boolean), entry, sourceInputs: preparedInputs, openedWorkspaceIds, openBoundary: replaced.report };
+}
+
+export function mergeWorkspaceEntrypointSet({
+  lifecycle,
+  state = {},
+  sourceInputs = [],
+  entry = null,
+  annotateWorkspace = null
+} = {}) {
+  const inputs = normalizeSourceInputs(sourceInputs);
+  if (!inputs.length) return { ok: false, error: 'workspace.entrypoint-set.empty', message: 'Workspace entrypoint has no mergeable workspace set.', state, entry, sourceInputs: [] };
+  if (!lifecycle?.createWorkspace || !lifecycle?.addWorkspaceSource) return { ok: false, error: 'workspace.lifecycle.incomplete', message: 'Workspace lifecycle cannot merge workspace entrypoints.', state, entry, sourceInputs: [] };
+
+  let next = cloneLifecycleState(lifecycle, state);
+  const originalActiveWorkspaceId = next.activeWorkspaceId || '';
+  const preparedInputs = [];
+  const touchedWorkspaceIds = [];
+  let createdCount = 0;
+  for (const sourceInput of inputs) {
+    let workspace = findWorkspaceForIncomingSource(next, sourceInput);
+    const existingSource = workspace ? findConfiguredSource(workspace, sourceInput) : null;
+    const alreadyLoaded = Boolean(existingSource && sourceMaterializationCompleteEnough(existingSource, sourceInput));
+    if (!workspace) {
+      const created = lifecycle.createWorkspace(next, defaultWorkspaceInput(sourceInput), {});
+      if (!created?.ok) continue;
+      next = created.state;
+      workspace = created.workspace;
+      createdCount += 1;
+    }
+    if (typeof annotateWorkspace === 'function') annotateWorkspace({ state: next, workspaceId: workspace.id, workspace, sourceInput, entry, mode: alreadyLoaded ? 'merge-existing-noop' : (createdCount && touchedWorkspaceIds.length === 0 ? 'merge-created' : 'merge-refresh') });
+    if (alreadyLoaded) {
+      touchedWorkspaceIds.push(workspace.id);
+      continue;
+    }
+    const added = addConfiguredSourceToWorkspace(lifecycle, next, workspace.id, sourceInput, { discoveryState: 'deferred' });
+    if (added?.ok) {
+      next = added.state;
+      touchedWorkspaceIds.push(workspace.id);
+      preparedInputs.push(Object.assign({}, sourceInput, { workspaceId: workspace.id, sourceId: added.source?.id || sourceInput.sourceId || '' }));
+    }
+  }
+  if (!touchedWorkspaceIds.length) return { ok: false, error: 'workspace.merge.no-entrypoints', message: 'Workspace entrypoint has no usable workspace set.', state, entry, sourceInputs: [] };
+  if (originalActiveWorkspaceId && (next.workspaces || []).some((workspace) => workspace.id === originalActiveWorkspaceId)) next.activeWorkspaceId = originalActiveWorkspaceId;
+  else next.activeWorkspaceId = touchedWorkspaceIds[0] || next.activeWorkspaceId || '';
+  const workspace = (next.workspaces || []).find((item) => item.id === touchedWorkspaceIds[0]) || null;
+  return { ok: true, state: next, workspace, entry, sourceInputs: preparedInputs, merge: { touchedWorkspaceIds, createdCount, skippedLoads: inputs.length - preparedInputs.length } };
+}
+
+export function normalizeWorkspaceEntrypointSet(sourceInputs = []) {
+  return normalizeSourceInputs(sourceInputs);
+}
+
+function normalizeSourceInputs(sourceInputs = []) {
+  const seen = new Set();
+  const output = [];
+  for (const input of Array.isArray(sourceInputs) ? sourceInputs : []) {
+    if (!input || !String(input.repository || input.repo || '').trim()) continue;
+    const label = String(input.label || '').trim().toLowerCase();
+    const plan = sourceSignature(input);
+    const key = `${label}|${plan}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    output.push(Object.assign({}, input));
+  }
+  return output;
+}
+
+function cloneLifecycleState(lifecycle, state) {
+  if (typeof lifecycle?.cloneState === 'function') return lifecycle.cloneState(state);
+  return JSON.parse(JSON.stringify(state && typeof state === 'object' ? state : { workspaces: [], activeWorkspaceId: '' }));
+}
+
+function defaultWorkspaceInput(sourceInput = {}) {
+  return {
+    name: sourceInput.label || sourceInput.workspaceLabel || sourceInput.repository || sourceInput.repo || 'Workspace',
+    boundary: 'workspace entrypoint set; source materialization is explicit'
+  };
+}