@tiinex/core 0.1.1

package/src/export/package.sourceReference.js

@@ -0,0 +1,81 @@
+import { externalWebArtifactUrl, normalizeExternalWebArtifactUrl } from '../sources/source.explicitTargets.js';
+
+const EXACT_GITHUB_COMMIT = /^[0-9a-f]{40}$/i;
+
+export function projectPackageSourceReference(material = {}, options = {}) {
+  const source = material.source || options.source || {};
+  const sourceTarget = material.sourceTarget || options.sourceTarget || {};
+  const adapterId = String(source.adapterId || options.adapterId || '').trim();
+  const repo = String(source.repo || source.repository || source.config?.repo || options.repo || '').trim();
+  const configuredRef = String(source.ref || source.config?.ref || source.resolvedRef || options.ref || '').trim();
+  const materializedCommit = exactCommit(sourceTarget.materializedCommit || source.materializedCommit || source.commit || options.materializedCommit);
+  const inputTarget = exactInputTarget(material, sourceTarget, adapterId);
+  const sourceArtifactPath = String(sourceTarget.sourceArtifactPath || options.sourceArtifactPath || (sourceTarget.surface === 'repoFiles' ? material.path || '' : '')).trim();
+  const path = sourceArtifactPath || String(options.path || material.path || '').trim();
+  const targetKind = String(sourceTarget.targetKind || source.sourceKind || options.targetKind || '').trim();
+  const surface = String(sourceTarget.surface || options.surface || '').trim();
+  const rawUrl = normalizeExternalWebArtifactUrl(sourceTarget.rawUrl || source.url || options.rawUrl || '');
+  const refKind = materializedCommit ? 'immutable-commit' : configuredRef ? 'mutable-or-unqualified-ref' : 'unpinned';
+  const githubTargetReady = adapterId === 'github' && Boolean(repo) && Boolean(path || inputTarget);
+  const externalTargetReady = adapterId !== 'github' && Boolean(inputTarget);
+  const exactTarget = githubTargetReady || externalTargetReady;
+  const status = adapterId === 'github'
+    ? (githubTargetReady && materializedCommit ? 'pinned-reference' : 'degraded-reference')
+    : (externalTargetReady ? 'exact-target-reference' : 'degraded-reference');
+
+  return deepFreeze({
+    schema: 'tiinex.export.package.source-target.v2',
+    adapterId,
+    status,
+    exactTarget,
+    immutability: materializedCommit ? 'immutable-materialized-commit' : (exactTarget ? 'target-exact-content-not-immutable' : 'degraded'),
+    repo,
+    configuredRef,
+    materializedCommit,
+    ref: materializedCommit || configuredRef,
+    refKind,
+    path,
+    sourceArtifactPath,
+    surface,
+    targetKind,
+    inputTarget,
+    rawUrl,
+    sourceId: String(source.id || ''),
+    sourceKind: String(source.sourceKind || source.kind || ''),
+    boundary: String(source.boundary || material.importBoundary || options.boundary || ''),
+    unavailable: Boolean(options.unavailable || material.previewState === 'metadata-only' || material.previewState === 'omitted-large')
+  });
+}
+
+export function isExactGithubCommit(value = '') {
+  return EXACT_GITHUB_COMMIT.test(String(value || '').trim());
+}
+
+export function sourceReferencePackageStatus(target = {}) {
+  if (target.adapterId === 'github') return target.materializedCommit && target.repo && (target.path || target.inputTarget) ? 'pinned-reference' : 'degraded-reference';
+  return target.inputTarget ? 'exact-target-reference' : 'degraded-reference';
+}
+
+function exactCommit(value = '') {
+  const text = String(value || '').trim();
+  return EXACT_GITHUB_COMMIT.test(text) ? text.toLowerCase() : '';
+}
+
+function exactInputTarget(material = {}, target = {}, adapterId = '') {
+  const explicit = String(target.inputTarget || '').trim();
+  if (explicit) {
+    if (adapterId === 'github') return explicit;
+    return normalizeExternalWebArtifactUrl(explicit) || explicit;
+  }
+  const external = externalWebArtifactUrl(material);
+  if (external) return external;
+  const permalink = String(material.source?.permalink || material.source?.config?.permalink || '').trim();
+  return permalink;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}

package/src/export/package.workspaceContext.js

@@ -0,0 +1,144 @@
+import { projectPackageSourceReference } from './package.sourceReference.js';
+import { schemaIdForRecord } from '../schemas/schema.identity.js';
+
+export const EXPORT_WORKSPACE_CONTEXT_SCHEMA_ID = 'tiinex.export.package.workspace-context.v1';
+
+export function buildExportWorkspaceContext(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const assets = Array.isArray(input.assets) ? input.assets : (Array.isArray(workspace.assets) ? workspace.assets : []);
+  const workspaceArtifacts = records.filter(isWorkspaceArtifactRecord).map(workspaceArtifactDescriptor);
+  const workspaceImport = sanitizeWorkspaceImport(workspace.workspaceImport || {});
+  const localWorkspaceMarkdown = localOwnedWorkspaceMarkdown(workspace, workspaceImport);
+  const sources = (Array.isArray(workspace.sources) ? workspace.sources : []).map(sourceDescriptor);
+  const sourceOrder = (Array.isArray(workspace.sourceOrder) ? workspace.sourceOrder : []).map(String);
+  const memberBindings = (Array.isArray(workspace.workspaceMemberBindings) ? workspace.workspaceMemberBindings : []).map(sanitizeMemberBinding).filter(Boolean);
+  const materialMembership = Object.freeze({
+    recordIds: Object.freeze(records.map((record) => String(record.id || record.path || '')).filter(Boolean)),
+    assetIds: Object.freeze(assets.map((asset) => String(asset.id || asset.path || '')).filter(Boolean)),
+    workspaceArtifactIds: Object.freeze(workspaceArtifacts.map((artifact) => artifact.id).filter(Boolean))
+  });
+  const markdownPackagePath = localWorkspaceMarkdown ? 'context/workspace.workspace.md' : '';
+  return deepFreeze({
+    schema: EXPORT_WORKSPACE_CONTEXT_SCHEMA_ID,
+    id: String(workspace.id || ''),
+    name: String(workspace.name || workspace.title || 'Workspace'),
+    title: String(workspace.title || workspace.name || 'Workspace'),
+    createdAt: String(workspace.createdAt || ''),
+    kind: String(workspace.kind || 'workspace'),
+    mode: String(workspace.mode || 'feed'),
+    workspaceImport,
+    workspaceMarkdown: Object.freeze({
+      ownership: localWorkspaceMarkdown ? 'owned-local' : (workspace.workspaceMarkdown ? 'reference-only-or-unqualified' : 'absent'),
+      available: Boolean(localWorkspaceMarkdown),
+      packagePath: markdownPackagePath,
+      bytes: new TextEncoder().encode(localWorkspaceMarkdown).byteLength
+    }),
+    sources: Object.freeze(sources),
+    sourceOrder: Object.freeze(sourceOrder),
+    workspaceArtifacts: Object.freeze(workspaceArtifacts),
+    workspaceMemberBindings: Object.freeze(memberBindings),
+    materialMembership,
+    boundary: 'Canonical workspace context projection for handoff/re-ingest. It preserves workspace/source configuration truth without turning source references into local leaves or making directory placement semantic identity.'
+  });
+}
+
+export function workspaceContextOwnedMarkdown(workspace = {}) {
+  const workspaceImport = sanitizeWorkspaceImport(workspace.workspaceImport || {});
+  return localOwnedWorkspaceMarkdown(workspace, workspaceImport);
+}
+
+function localOwnedWorkspaceMarkdown(workspace = {}, workspaceImport = {}) {
+  const markdown = String(workspace.workspaceMarkdown || '');
+  if (!markdown) return '';
+  const mode = String(workspaceImport.sourceMode || workspace.sourceMode || '').trim().toLowerCase();
+  const boundary = String(workspaceImport.boundary || workspace.source?.boundary || '').trim().toLowerCase();
+  const localOwned = mode.startsWith('local') || mode.startsWith('manual') || mode.startsWith('package-import') || boundary.includes('browser-local') || workspaceImport.localDraft === true;
+  return localOwned ? markdown : '';
+}
+
+function isWorkspaceArtifactRecord(record = {}) {
+  return Boolean(record.workspaceArtifactRole?.openEligible || record.workspaceArtifactRole?.mergeEligible)
+    || schemaIdForRecord(record) === 'tiinex.workspace.v1'
+    || /\.workspace\.md$/i.test(String(record.sourceTarget?.sourceArtifactPath || record.path || ''));
+}
+
+function workspaceArtifactDescriptor(record = {}) {
+  const sourceTarget = projectPackageSourceReference(record);
+  return deepFreeze({
+    id: String(record.id || record.path || ''),
+    title: String(record.title || record.path || 'Workspace artifact'),
+    path: String(record.path || ''),
+    schemaId: schemaIdForRecord(record),
+    sourceMode: String(record.sourceMode || ''),
+    sourceReference: sourceTarget,
+    openEligible: record.workspaceArtifactRole?.openEligible !== false,
+    mergeEligible: record.workspaceArtifactRole?.mergeEligible !== false
+  });
+}
+
+function sourceDescriptor(source = {}) {
+  const projection = projectPackageSourceReference({ source, sourceTarget: {} }, { unavailable: false });
+  return deepFreeze({
+    id: String(source.id || ''),
+    label: String(source.label || ''),
+    adapterId: String(source.adapterId || ''),
+    sourceKind: String(source.sourceKind || source.kind || ''),
+    repo: String(source.repo || source.config?.repo || ''),
+    ref: String(source.ref || source.config?.ref || ''),
+    requestedRef: String(source.requestedRef ?? source.config?.requestedRef ?? ''),
+    materializedCommit: String(source.materializedCommit || ''),
+    rootPath: String(source.rootPath || source.config?.rootPath || ''),
+    boundary: String(source.boundary || ''),
+    repoDiscovery: Boolean(source.repoDiscovery),
+    issueDiscovery: Boolean(source.issueDiscovery),
+    issueUrls: String(source.issueUrls || source.config?.issueUrls || ''),
+    explicitFileRefs: Object.freeze(Array.isArray(source.explicitFileRefs) ? source.explicitFileRefs.map(String) : []),
+    exactReference: projection
+  });
+}
+
+function sanitizeWorkspaceImport(value = {}) {
+  return deepFreeze({
+    schema: String(value.schema || 'tiinex.workspace.import.v1'),
+    path: String(value.path || ''),
+    sourceMode: String(value.sourceMode || ''),
+    boundary: String(value.boundary || ''),
+    openedFromWorkspaceId: String(value.openedFromWorkspaceId || ''),
+    contextReferenceId: String(value.contextReferenceId || ''),
+    localDraft: value.localDraft === true
+  });
+}
+
+function sanitizeMemberBinding(binding = {}) {
+  const descriptor = binding.descriptorTarget || {};
+  const identity = binding.memberIdentity || {};
+  if (!descriptor.externalTarget || !identity.key) return null;
+  return deepFreeze({
+    schema: String(binding.schema || 'tiinex.workspace.memberBinding.v1'),
+    descriptorTarget: {
+      schema: String(descriptor.schema || 'tiinex.publicTarget.v1'),
+      adapterId: String(descriptor.adapterId || ''),
+      targetKind: String(descriptor.targetKind || 'workspace'),
+      externalTarget: String(descriptor.externalTarget || ''),
+      repository: String(descriptor.repository || ''),
+      ref: String(descriptor.ref || ''),
+      path: String(descriptor.path || '')
+    },
+    memberIdentity: {
+      schema: String(identity.schema || 'tiinex.workspace.memberIdentity.v1'),
+      kind: String(identity.kind || 'semantic'),
+      key: String(identity.key || ''),
+      name: String(identity.name || ''),
+      label: String(identity.label || ''),
+      sourceKind: String(identity.sourceKind || ''),
+      sourceSignature: String(identity.sourceSignature || '')
+    }
+  });
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}

package/src/export/package.zip.js

@@ -0,0 +1,128 @@
+import { inspectExportPackageBundle } from './package.builder.js';
+import { packageFileByteView, packageFileBytes } from './package.bytes.js';
+import { inspectTreeExportBundle } from './tree.bundle.js';
+
+export function exportPackageZipUint8Array(bundle = {}) {
+  const inspection = inspectExportPackageBundle(bundle);
+  if (inspection.status !== 'valid') throw new Error('export.package.zip.bundle.invalid');
+  return exportFileMapZipUint8Array(bundle.files || [], 'export.package.zip.path.invalid');
+}
+
+export function exportTreeZipUint8Array(bundle = {}) {
+  const inspection = inspectTreeExportBundle(bundle);
+  if (inspection.status === 'invalid') throw new Error('export.tree.zip.bundle.invalid');
+  return exportFileMapZipUint8Array(bundle.files || [], 'export.tree.zip.path.invalid');
+}
+
+export function exportFileMapZipUint8Array(files = [], invalidPathError = 'export.zip.path.invalid') {
+  const entries = (files || []).map((file) => ({ name: safeZipPath(file.path), data: packageFileByteView(file) }));
+  if (entries.some((entry) => !entry.name)) throw new Error(invalidPathError);
+  return storedZip(entries);
+}
+
+export function exportPackageZipBlob(bundle = {}) {
+  const bytes = exportPackageZipUint8Array(bundle);
+  return new Blob([bytes], { type: 'application/zip' });
+}
+
+export function exportTreeZipBlob(bundle = {}) {
+  const bytes = exportTreeZipUint8Array(bundle);
+  return new Blob([bytes], { type: 'application/zip' });
+}
+
+function storedZip(entries) {
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = utf8(entry.name);
+    const data = entry.data instanceof Uint8Array ? entry.data : utf8(String(entry.data || ''));
+    const crc = crc32(data);
+    const local = new Uint8Array(30 + name.length);
+    const view = new DataView(local.buffer);
+    view.setUint32(0, 0x04034b50, true);
+    view.setUint16(4, 20, true);
+    view.setUint16(6, 0x0800, true);
+    view.setUint16(8, 0, true);
+    view.setUint16(10, 0, true);
+    view.setUint16(12, 0x0021, true); // 1980-01-01, aligned with portable deterministic ZIP output.
+    view.setUint32(14, crc, true);
+    view.setUint32(18, data.length, true);
+    view.setUint32(22, data.length, true);
+    view.setUint16(26, name.length, true);
+    view.setUint16(28, 0, true);
+    local.set(name, 30);
+    localParts.push(local, data);
+
+    const central = new Uint8Array(46 + name.length);
+    const cv = new DataView(central.buffer);
+    cv.setUint32(0, 0x02014b50, true);
+    cv.setUint16(4, 20, true);
+    cv.setUint16(6, 20, true);
+    cv.setUint16(8, 0x0800, true);
+    cv.setUint16(10, 0, true);
+    cv.setUint16(12, 0, true);
+    cv.setUint16(14, 0x0021, true);
+    cv.setUint32(16, crc, true);
+    cv.setUint32(20, data.length, true);
+    cv.setUint32(24, data.length, true);
+    cv.setUint16(28, name.length, true);
+    cv.setUint16(30, 0, true);
+    cv.setUint16(32, 0, true);
+    cv.setUint16(34, 0, true);
+    cv.setUint16(36, 0, true);
+    cv.setUint32(38, 0, true);
+    cv.setUint32(42, offset, true);
+    central.set(name, 46);
+    centralParts.push(central);
+    offset += local.length + data.length;
+  }
+  const centralDirectory = concat(centralParts);
+  const end = new Uint8Array(22);
+  const ev = new DataView(end.buffer);
+  ev.setUint32(0, 0x06054b50, true);
+  ev.setUint16(4, 0, true);
+  ev.setUint16(6, 0, true);
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, centralDirectory.length, true);
+  ev.setUint32(16, offset, true);
+  ev.setUint16(20, 0, true);
+  return concat([...localParts, centralDirectory, end]);
+}
+
+function safeZipPath(value = '') {
+  const input = String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = [];
+  for (const part of input.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') return '';
+    parts.push(part.replace(/[\u0000-\u001f<>:"|?*]/g, '_'));
+  }
+  return parts.join('/');
+}
+
+function utf8(value = '') { return new TextEncoder().encode(String(value || '')); }
+function concat(parts = []) {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) { out.set(part, offset); offset += part.length; }
+  return out;
+}
+
+const CRC_TABLE = makeCrcTable();
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+function makeCrcTable() {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) value = (value & 1) ? (0xedb88320 ^ (value >>> 1)) : (value >>> 1);
+    table[index] = value >>> 0;
+  }
+  return table;
+}

package/src/export/tree.bundle.js

@@ -0,0 +1,278 @@
+import { buildRecordLogicalPathMap, recordLogicalPathFromMap } from '../workspaces/workspace.recordPaths.js';
+import { resolveTransportPlan } from '../sources/transport.levels.js';
+import { isWorkspaceRecord } from '../actions/record.actions.js';
+export const TREE_EXPORT_BUNDLE_SCHEMA_ID = 'tiinex.export.tree.bundle.v1';
+
+export function buildWorkspaceTreeExportBundle(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const assets = Array.isArray(input.assets) ? input.assets : (Array.isArray(workspace.assets) ? workspace.assets : []);
+  const includeAssets = input.includeAssets !== false;
+  const includeWorkspaceEntries = input.includeWorkspaceEntries !== false;
+  const builtAt = typeof input.clock === 'function' ? input.clock() : (input.builtAt || new Date().toISOString());
+  const transport = resolveTransportPlan(input.sourceConfig || workspace.sourceConfig || {}, 'local-download', { defaultLevel: 'TL0', allowFallback: false });
+  const findings = [];
+  const files = [];
+  const recordPathMap = buildRecordLogicalPathMap(records);
+
+  if (includeWorkspaceEntries) {
+    for (const entry of collectWorkspaceTreeEntries(workspace, input, records)) {
+      const file = treeFileForWorkspaceEntry(entry, findings);
+      if (file) files.push(file);
+    }
+  }
+
+  for (const record of records) {
+    if (isWorkspaceRecord(record)) continue;
+    const file = treeFileForRecord(record, findings, recordPathMap);
+    if (file) files.push(file);
+  }
+  if (includeAssets) {
+    for (const asset of assets) {
+      const file = treeFileForAsset(asset, findings);
+      if (file) files.push(file);
+    }
+  }
+
+  const unique = uniqueFiles(files, findings);
+  const counts = Object.freeze({
+    files: unique.length,
+    records: unique.filter((file) => file.kind === 'artifact-markdown').length,
+    workspaceEntries: unique.filter((file) => file.kind === 'workspace-markdown').length,
+    assets: unique.filter((file) => file.kind === 'asset-content').length,
+    skippedRecords: findings.filter((finding) => finding.code === 'export.tree.record.content-missing').length,
+    skippedAssets: findings.filter((finding) => finding.code === 'export.tree.asset.content-unavailable').length,
+    warnings: findings.filter((finding) => finding.severity === 'warning').length,
+    errors: findings.filter((finding) => finding.severity === 'error').length,
+    findings: findings.length
+  });
+  const status = counts.errors ? 'blocked' : counts.warnings ? 'degraded' : 'ready';
+
+  return deepFreeze({
+    schema: TREE_EXPORT_BUNDLE_SCHEMA_ID,
+    exportType: 'tree',
+    transportLevel: transport.selectedLevel,
+    builtAt,
+    status,
+    boundary: 'Ordinary local download tree export. File paths mirror the logical Tiinex tree; no package envelope, receipts, source mutation, remote fetch, or provenance inference is included.',
+    packageEnvelope: false,
+    sourceMutation: false,
+    remoteFetch: false,
+    transport,
+    counts,
+    files: unique,
+    findings
+  });
+}
+
+export function inspectTreeExportBundle(bundle = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const findings = [];
+  if (bundle.schema !== TREE_EXPORT_BUNDLE_SCHEMA_ID) findings.push(treeFinding('error', 'export.tree.schema.invalid', 'Tree export bundle schema is invalid.'));
+  if (bundle.packageEnvelope === true || files.some((file) => String(file.path || '').startsWith('tiinex.package/'))) {
+    findings.push(treeFinding('error', 'export.tree.package-envelope.detected', 'Ordinary tree export must not contain package envelope control files.'));
+  }
+  const seen = new Set();
+  for (const file of files) {
+    const path = normalizeTreePath(file.path || '');
+    if (!path) findings.push(treeFinding('error', 'export.tree.file.path-invalid', 'Tree export file has an invalid path.', { path: file.path || '' }));
+    if (path && seen.has(path)) findings.push(treeFinding('error', 'export.tree.file.path-duplicate', 'Tree export file path is duplicated.', { path }));
+    seen.add(path);
+    if (isPackageEnvelopePath(path)) findings.push(treeFinding('error', 'export.tree.package-prefix.visible', 'Tree export path still contains a package envelope prefix.', { path }));
+  }
+  return Object.freeze({
+    schema: 'tiinex.export.tree.bundle.inspection.v1',
+    status: findings.some((finding) => finding.severity === 'error') ? 'invalid' : findings.some((finding) => finding.severity === 'warning') ? 'degraded' : 'valid',
+    counts: Object.freeze({ files: files.length, findings: findings.length, errors: findings.filter((finding) => finding.severity === 'error').length, warnings: findings.filter((finding) => finding.severity === 'warning').length }),
+    findings: Object.freeze(findings)
+  });
+}
+
+
+function collectWorkspaceTreeEntries(workspace = {}, input = {}, records = []) {
+  const entries = [];
+  const seen = new Set();
+  const push = (entry = {}, role = 'workspace') => {
+    const markdown = String(entry.markdown || entry.workspaceMarkdown || entry.content || '');
+    if (!markdown) return;
+    const path = normalizeWorkspaceEntryPath(entry.path || entry.logicalPath || entry.name || `${slugPart(entry.title || workspace.title || workspace.name || 'workspace')}.workspace.md`);
+    if (!path) return;
+    const key = path.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    entries.push(Object.assign({}, entry, { path, markdown, workspaceEntryRole: role }));
+  };
+
+  if (input.workspaceEntry) push(input.workspaceEntry, input.workspaceEntry.workspaceEntryRole || 'current-workspace');
+  const importPath = workspace.workspaceImport?.path || '';
+  const importMarkdown = workspace.workspaceMarkdown || workspace.workspaceImport?.markdown || '';
+  if (importPath || importMarkdown) push({ path: importPath, markdown: importMarkdown, title: workspace.title || workspace.name || '' }, 'current-workspace');
+  for (const record of Array.isArray(records) ? records : []) {
+    if (!isWorkspaceRecord(record)) continue;
+    push({ path: record.path || record.sourcePath || '', markdown: record.markdown || record.content || '', title: record.title || '', id: record.id || '', source: record.source || {}, boundary: record.boundary || '' }, 'workspace-artifact-record');
+  }
+  for (const entry of Array.isArray(workspace.workspaceMergedEntries) ? workspace.workspaceMergedEntries : []) push(entry, 'merged-workspace');
+  // Compatibility-only: old checkpoints/packages may still contain candidate objects.
+  for (const entry of Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []) push(entry, 'legacy-workspace-candidate');
+  return entries;
+}
+
+function treeFileForWorkspaceEntry(entry = {}, findings = []) {
+  const path = normalizeWorkspaceEntryPath(entry.path || entry.name || 'workspace.workspace.md');
+  const content = String(entry.markdown || entry.workspaceMarkdown || entry.content || '');
+  if (!path) {
+    findings.push(treeFinding('error', 'export.tree.workspace.path-missing', 'Workspace entry cannot be exported without a safe logical path.', { workspaceEntryId: entry.id || '' }));
+    return null;
+  }
+  if (isPackageEnvelopePath(path)) {
+    findings.push(treeFinding('error', 'export.tree.workspace.package-path-refused', 'Workspace entry resolved to a package envelope path; ordinary tree export requires logical workspace paths.', { workspaceEntryId: entry.id || '', path }));
+    return null;
+  }
+  if (!content) {
+    findings.push(treeFinding('warning', 'export.tree.workspace.content-missing', 'Workspace entry has no loaded Markdown content and was omitted from the ordinary tree export.', { workspaceEntryId: entry.id || '', path }));
+    return null;
+  }
+  return makeTextFile(path, 'workspace-markdown', content, {
+    workspaceEntryId: entry.id || '',
+    title: entry.title || '',
+    sourceBoundary: entry.source?.boundary || entry.boundary || '',
+    presentationPath: path,
+    workspaceEntryRole: entry.workspaceEntryRole || 'workspace'
+  });
+}
+
+function normalizeWorkspaceEntryPath(path = '') {
+  const clean = normalizeTreePath(path || 'workspace.workspace.md');
+  if (!clean) return '';
+  if (/\.workspace\.md$/i.test(clean)) return clean;
+  return clean.replace(/(?:\.md|\.markdown)?$/i, '.workspace.md');
+}
+
+function treeFileForRecord(record = {}, findings = [], recordPathMap = null) {
+  const logicalPath = recordLogicalPathFromMap(record, recordPathMap);
+  const path = normalizeTreePath(logicalPath || record.name || record.title || 'artifact.md');
+  const content = String(record.markdown || record.content || record.text || '');
+  if (!path) {
+    findings.push(treeFinding('error', 'export.tree.record.path-missing', 'Record cannot be exported without a safe logical path.', { recordId: record.id || '' }));
+    return null;
+  }
+  if (isPackageEnvelopePath(path)) {
+    findings.push(treeFinding('error', 'export.tree.record.package-path-refused', 'Record resolved to a package envelope path; ordinary tree export requires logical material paths.', { recordId: record.id || '', path, logicalPath }));
+    return null;
+  }
+  if (!content) {
+    findings.push(treeFinding('warning', 'export.tree.record.content-missing', 'Record has no loaded Markdown content and was omitted from the ordinary tree export.', { recordId: record.id || '', path }));
+    return null;
+  }
+  return makeTextFile(path, 'artifact-markdown', content, {
+    recordId: record.id || '',
+    title: record.title || '',
+    sourceBoundary: record.source?.boundary || record.boundary || '',
+    provenancePath: record.sourcePath || record.sourceTarget?.sourceArtifactPath || record.snapshot?.sourceArtifactPath || '',
+    presentationPath: path,
+    logicalPath
+  });
+}
+
+function treeFileForAsset(asset = {}, findings = []) {
+  const path = normalizeTreePath(asset.path || asset.name || 'asset');
+  const content = typeof asset.content === 'string' && asset.content
+    ? asset.content
+    : typeof asset.dataUrl === 'string' && asset.dataUrl
+      ? asset.dataUrl
+      : typeof asset.text === 'string'
+        ? asset.text
+        : '';
+  if (!path) {
+    findings.push(treeFinding('error', 'export.tree.asset.path-missing', 'Asset cannot be exported without a safe logical path.', { assetId: asset.id || '' }));
+    return null;
+  }
+  if (!content) {
+    findings.push(treeFinding('warning', 'export.tree.asset.content-unavailable', 'Asset content was unavailable and was omitted from the ordinary tree export.', { assetId: asset.id || '', path }));
+    return null;
+  }
+  return makeTextFile(path, 'asset-content', content, {
+    assetId: asset.id || '',
+    title: asset.title || asset.name || '',
+    mediaType: asset.type || asset.mediaType || asset.mimeType || 'application/octet-stream',
+    presentationPath: path
+  });
+}
+
+function makeTextFile(path, kind, content, extra = {}) {
+  const text = String(content || '');
+  return Object.freeze(Object.assign({
+    path: normalizeTreePath(path),
+    kind,
+    mediaType: extra.mediaType || (kind === 'artifact-markdown' ? 'text/markdown' : 'application/octet-stream'),
+    bytes: text.length,
+    content: text
+  }, omit(extra, ['mediaType'])));
+}
+
+function uniqueFiles(files = [], findings = []) {
+  const seen = new Map();
+  return files.map((file) => {
+    const path = normalizeTreePath(file.path || '');
+    if (!seen.has(path)) {
+      seen.set(path, 0);
+      return file;
+    }
+    const next = seen.get(path) + 1;
+    seen.set(path, next);
+    const renamedPath = addPathSuffix(path, `duplicate-${next}`);
+    findings.push(treeFinding('warning', 'export.tree.path-deduped', 'Duplicate tree export path was made unique.', { path, renamedPath }));
+    return Object.freeze(Object.assign({}, file, { path: renamedPath, presentationPath: renamedPath }));
+  });
+}
+
+function addPathSuffix(path, suffix) {
+  const slash = path.lastIndexOf('/');
+  const dot = path.lastIndexOf('.');
+  if (dot <= slash) return `${path}.${suffix}`;
+  return `${path.slice(0, dot)}.${suffix}${path.slice(dot)}`;
+}
+
+export function normalizeTreePath(path = '') {
+  const input = String(path || '').trim().replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = [];
+  for (const part of input.split('/')) {
+    const clean = part.trim();
+    if (!clean || clean === '.') continue;
+    if (clean === '..') continue;
+    parts.push(clean.replace(/[\u0000-\u001f<>:"|?*]/g, '_'));
+  }
+  const output = parts.join('/');
+  if (!output) return '';
+  if (/\.(?:md|markdown|trace\.md|schema\.md|validator\.md|workspace\.md)$/i.test(output)) return output;
+  const leaf = output.split('/').filter(Boolean).pop() || '';
+  return leaf.includes('.') ? output : `${output}.md`;
+}
+
+function slugPart(value = '') {
+  return String(value || 'workspace').toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'workspace';
+}
+
+function isPackageEnvelopePath(path = '') {
+  const clean = String(path || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  return clean === 'artifacts' || clean.startsWith('artifacts/')
+    || clean === 'tiinex.package' || clean.startsWith('tiinex.package/')
+    || clean === 'workspace-candidates' || clean.startsWith('workspace-candidates/');
+}
+
+function omit(value = {}, keys = []) {
+  const remove = new Set(keys);
+  const out = {};
+  for (const [key, item] of Object.entries(value || {})) if (!remove.has(key)) out[key] = item;
+  return out;
+}
+
+function treeFinding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const item of Object.values(value)) deepFreeze(item);
+  return value;
+}