@tiinex/core 0.1.1

package/src/export/package.manifest.js

@@ -0,0 +1,401 @@
+import { buildExportPackagePreflight } from './package.preflight.js';
+import { packageAssetBytes, utf8Bytes } from './package.bytes.js';
+
+export const EXPORT_PACKAGE_MANIFEST_SCHEMA_ID = 'tiinex.export.package.manifest.v1';
+export const EXPORT_PACKAGE_RECEIPT_SCHEMA_ID = 'tiinex.export.package.receipt.v1';
+export const EXPORT_PACKAGE_CONTRACT_SCHEMA_ID = 'tiinex.export.package.contract.v1';
+
+export function buildExportPackageManifest(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 workspaceCandidates = Array.isArray(input.workspaceCandidates) ? input.workspaceCandidates : (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []);
+  const preflight = input.preflight || input.exportPackagePreflight || buildExportPackagePreflight(workspace, { records, assets, workspaceCandidates });
+  const createdAt = typeof input.clock === 'function' ? input.clock() : (input.createdAt || new Date().toISOString());
+  const recordIndex = indexByIdAndPath(records);
+  const assetIndex = indexByIdAndPath(assets);
+  const candidateIndex = indexByIdAndPath(workspaceCandidates);
+
+  const localDrafts = (preflight.localDraftEntries || []).map((entry) => manifestLocalDraftEntry(entry, recordIndex));
+  const sourceReferences = (preflight.sourceReferenceEntries || []).map((entry) => manifestSourceReferenceEntry(entry));
+  const assetEntries = (preflight.assetEntries || []).map((entry) => manifestAssetEntry(entry, assetIndex));
+  const contextCandidates = (preflight.workspaceCandidateEntries || []).map((entry) => manifestWorkspaceCandidateEntry(entry, candidateIndex));
+  const workspaceContext = manifestWorkspaceContextEntry(preflight.workspaceContext || {}, workspace);
+  const blocked = (preflight.blockedLocalEntries || []).map((entry) => manifestBlockedEntry(entry));
+  const findings = (preflight.findings || []).map((finding) => manifestFinding('preflight', finding));
+
+  const packageScope = Object.freeze({
+    workspaceId: workspace.id || '',
+    workspaceTitle: workspace.title || workspace.name || 'workspace',
+    materialBoundary: 'bounded-loaded-workspace',
+    includesLocalDraftMarkdown: localDrafts.length > 0,
+    includesSourceReferences: sourceReferences.length > 0,
+    includesAssets: assetEntries.length > 0,
+    includesWorkspaceContextCandidates: contextCandidates.length > 0,
+    includesWorkspaceContext: true,
+    governanceBoundary: preflight.governanceBoundary || null,
+    sourceMutation: false,
+    remoteFetch: false,
+    packageZipCreated: false
+  });
+
+  const material = Object.freeze({
+    localDrafts: Object.freeze(localDrafts),
+    sourceReferences: Object.freeze(sourceReferences),
+    assets: Object.freeze(assetEntries),
+    workspaceContextCandidates: Object.freeze(contextCandidates),
+    workspaceContext,
+    blocked: Object.freeze(blocked)
+  });
+  const counts = Object.freeze({
+    entries: localDrafts.length + sourceReferences.length + assetEntries.length + contextCandidates.length + 1,
+    localDrafts: localDrafts.length,
+    sourceReferences: sourceReferences.length,
+    pinnedSourceReferences: sourceReferences.filter((entry) => entry.status === 'pinned-reference').length,
+    degradedSourceReferences: sourceReferences.filter((entry) => entry.status !== 'pinned-reference').length,
+    assets: assetEntries.length,
+    metadataOnlyAssets: assetEntries.filter((entry) => entry.status === 'metadata-only').length,
+    workspaceContextCandidates: contextCandidates.length,
+    workspaceContext: 1,
+    blocked: blocked.length,
+    errors: findings.filter((finding) => finding.severity === 'error').length,
+    warnings: findings.filter((finding) => finding.severity === 'warning').length,
+    findings: findings.length
+  });
+  const status = counts.blocked || counts.errors ? 'blocked' : (preflight.status === 'blocked' ? 'blocked' : (preflight.status === 'degraded' || counts.warnings || counts.metadataOnlyAssets || counts.degradedSourceReferences || counts.workspaceContextCandidates ? 'degraded' : 'ready'));
+  const fingerprint = exportPackageManifestFingerprint({ packageScope, workspaceId: packageScope.workspaceId, status, material });
+  const packageId = `package:${safeToken(packageScope.workspaceId || 'workspace')}:${fingerprint}`;
+
+  return deepFreeze({
+    schema: EXPORT_PACKAGE_MANIFEST_SCHEMA_ID,
+    packageId,
+    createdAt,
+    workspaceId: packageScope.workspaceId,
+    title: `Tiinex export package manifest · ${packageScope.workspaceTitle}`,
+    status,
+    boundary: 'Manifest only. It describes a future bounded export package without creating a zip, mutating sources, or assigning new provenance.',
+    packageScope,
+    entryPolicy: Object.freeze({
+      localDrafts: 'Embed validated local draft Markdown as package artifacts while preserving local/draft boundary.',
+      sourceReferences: 'Package source-backed material as explicit pinned/degraded source references, not as new local leaves.',
+      assets: 'Package assets as assets; metadata-only assets require reselection or explicit metadata-only receipt.',
+      workspaceCandidates: 'Workspace candidates remain context candidates until explicit Open/Merge.',
+      blocked: 'Blocked material is listed as excluded; it is never silently converted into a valid Tiinex leaf.'
+    }),
+    material,
+    counts,
+    findings: Object.freeze(findings),
+    integrity: Object.freeze({
+      algorithm: 'tiinex-stable-fingerprint-v1',
+      fingerprint,
+      note: 'Deterministic manifest fingerprint for conformance and roundtrip checks; not a cryptographic content hash.'
+    })
+  });
+}
+
+
+export function exportPackageManifestFingerprint(manifest = {}) {
+  return stableFingerprint({
+    workspaceId: manifest.packageScope?.workspaceId || manifest.workspaceId || '',
+    status: manifest.status || 'unknown',
+    policy: 'tiinex-export-package-manifest-v1',
+    governanceBoundary: manifest.packageScope?.governanceBoundary || null,
+    material: manifest.material || {}
+  });
+}
+
+export function buildExportPackageReceipt(manifest = {}, input = {}) {
+  const at = typeof input.clock === 'function' ? input.clock() : (input.at || new Date().toISOString());
+  const findings = Array.isArray(manifest.findings) ? manifest.findings : [];
+  const status = manifest.status === 'blocked' ? 'blocked' : (manifest.status === 'degraded' ? 'degraded' : 'ready');
+  const receiptFingerprint = stableFingerprint({
+    manifestSchema: manifest.schema,
+    packageId: manifest.packageId,
+    manifestFingerprint: manifest.integrity?.fingerprint || '',
+    status,
+    counts: manifest.counts || {}
+  });
+  return deepFreeze({
+    schema: EXPORT_PACKAGE_RECEIPT_SCHEMA_ID,
+    receiptId: `receipt:${safeToken(manifest.packageId || 'package')}:${receiptFingerprint}`,
+    packageId: manifest.packageId || '',
+    at,
+    operation: 'export-package-manifest-created',
+    state: status === 'blocked' ? 'blocked' : 'planned',
+    status,
+    boundary: 'Receipt records manifest planning only. No zip was written, no source was mutated, and no remote material was fetched.',
+    manifestFingerprint: manifest.integrity?.fingerprint || '',
+    counts: Object.freeze(Object.assign({ entries: 0, blocked: 0, errors: 0, warnings: 0 }, manifest.counts || {})),
+    guarantees: Object.freeze([
+      'Local/session material remains local unless an explicit later publication transition assigns a durable source.',
+      'Source-backed material remains a source reference and is not re-authored as a local draft.',
+      'Assets remain assets and are not converted into fake artifact leaves.',
+      'Blocked or degraded material is disclosed in findings before any future package builder may proceed.'
+    ]),
+    nextActions: Object.freeze(nextActionsForManifest(manifest)),
+    findings: Object.freeze(findings.map((finding) => manifestFinding('manifest', finding)))
+  });
+}
+
+export function buildExportPackageContract(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 workspaceCandidates = Array.isArray(input.workspaceCandidates) ? input.workspaceCandidates : (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []);
+  const preflight = input.preflight || input.exportPackagePreflight || buildExportPackagePreflight(workspace, { records, assets, workspaceCandidates });
+  const manifest = input.manifest || buildExportPackageManifest(workspace, Object.assign({}, input, { records, assets, workspaceCandidates, preflight }));
+  const receipt = input.receipt || buildExportPackageReceipt(manifest, input);
+  return deepFreeze({
+    schema: EXPORT_PACKAGE_CONTRACT_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    status: manifest.status || preflight.status || 'unknown',
+    boundary: 'No-mutation package planning contract: preflight, manifest, and receipt are produced together for conformance before an export builder exists.',
+    preflight,
+    manifest,
+    receipt
+  });
+}
+
+function manifestLocalDraftEntry(entry = {}, recordIndex = new Map()) {
+  const sourceRecord = lookupEntry(recordIndex, entry);
+  const markdown = sourceRecord?.markdown || sourceRecord?.content || sourceRecord?.text || '';
+  const path = normalizeRelativePath(entry.path || sourceRecord?.path || `${entry.id || 'draft'}.md`);
+  return Object.freeze({
+    id: entry.id || sourceRecord?.id || path,
+    title: entry.title || sourceRecord?.title || 'Local draft',
+    kind: 'artifact-markdown',
+    path,
+    packagePath: `artifacts/${path}`,
+    status: entry.status || 'ready',
+    mode: entry.mode || 'embed-local-draft-markdown',
+    boundary: entry.boundary || 'Package may embed this validated local draft. It remains local/draft material.',
+    content: Object.freeze({
+      available: Boolean(markdown),
+      mediaType: 'text/markdown',
+      bytes: utf8Bytes(markdown).byteLength,
+      fingerprint: markdown ? stableFingerprint(markdown) : '',
+      embeddedByFutureBuilder: Boolean(markdown)
+    })
+  });
+}
+
+function manifestSourceReferenceEntry(entry = {}) {
+  const target = entry.target || {};
+  const path = normalizeRelativePath(target.path || entry.path || `${entry.id || 'source-reference'}.source.json`);
+  return Object.freeze({
+    id: entry.id || path,
+    title: entry.title || 'Source reference',
+    kind: 'source-reference',
+    path,
+    packagePath: `sources/${safeToken(target.adapterId || entry.adapterId || 'source')}/${safeToken(target.repo || entry.repo || target.inputTarget || 'target')}/${safeToken(target.materializedCommit || target.configuredRef || target.ref || entry.ref || 'unpinned')}/${safeToken(entry.id || path)}.source.json`,
+    adapterId: target.adapterId || entry.adapterId || '',
+    repo: target.repo || entry.repo || '',
+    ref: target.ref || entry.ref || '',
+    status: entry.status || target.status || 'degraded-reference',
+    mode: entry.mode || 'preserve-source-reference',
+    boundary: entry.boundary || 'Package stores exact available source-target authority as a reference; it does not republish it.',
+    target: deepFreeze({ ...target })
+  });
+}
+
+function manifestAssetEntry(entry = {}, assetIndex = new Map()) {
+  const sourceAsset = lookupEntry(assetIndex, entry) || {};
+  const path = normalizeRelativePath(entry.path || sourceAsset.path || `${entry.id || 'asset'}`);
+  const byteProjection = packageAssetBytes(sourceAsset);
+  const contentAvailable = entry.status === 'content-available' && byteProjection.bytes.byteLength > 0;
+  const status = entry.status || (contentAvailable ? 'content-available' : 'metadata-only');
+  const id = entry.id || sourceAsset.id || path;
+  const packagePath = status === 'source-reference'
+    ? `sources/assets/${safeToken(id)}.asset.source.json`
+    : status === 'metadata-only'
+      ? `metadata/assets/${path}.asset.json`
+      : `assets/${path}`;
+  return Object.freeze({
+    id,
+    title: entry.title || sourceAsset.name || path,
+    kind: 'asset',
+    path,
+    packagePath,
+    mediaType: entry.mediaType || sourceAsset.type || sourceAsset.mimeType || byteProjection.mediaType || '',
+    byteSize: Number(entry.byteSize || sourceAsset.size || byteProjection.bytes.byteLength || 0),
+    status,
+    mode: entry.mode || (contentAvailable ? 'asset-content-entry' : 'asset-metadata-entry'),
+    boundary: entry.boundary || sourceAsset.source?.boundary || 'Asset boundary follows its intake source; assets are not fake leaves.',
+    sourceReference: entry.sourceReference ? deepFreeze({ ...entry.sourceReference }) : null,
+    content: Object.freeze({
+      available: contentAvailable,
+      bytes: contentAvailable ? byteProjection.bytes.byteLength : 0,
+      representation: contentAvailable ? byteProjection.representation : 'none',
+      note: contentAvailable ? 'Package builder embeds exact owned bytes.' : 'No owned bytes are claimed by this manifest entry.'
+    })
+  });
+}
+
+function manifestWorkspaceCandidateEntry(entry = {}, candidateIndex = new Map()) {
+  const sourceCandidate = lookupEntry(candidateIndex, entry);
+  const path = normalizeRelativePath(entry.path || sourceCandidate?.path || `${entry.id || 'workspace'}.workspace.md`);
+  return Object.freeze({
+    id: entry.id || sourceCandidate?.id || path,
+    title: entry.title || sourceCandidate?.title || path,
+    kind: 'workspace-candidate',
+    path,
+    packagePath: `workspace-candidates/${path}`,
+    status: entry.status || 'open-or-merge-required',
+    mode: entry.mode || 'context-candidate-reference',
+    boundary: entry.boundary || 'Workspace candidate is context material until explicit open/merge.'
+  });
+}
+
+function manifestWorkspaceContextEntry(context = {}, workspace = {}) {
+  const id = `workspace-context:${context.id || workspace.id || 'workspace'}`;
+  const packagePaths = ['context/workspace.json'];
+  if (context.workspaceMarkdown?.available) packagePaths.push(context.workspaceMarkdown.packagePath || 'context/workspace.workspace.md');
+  return Object.freeze({
+    id,
+    title: `Workspace context · ${context.title || workspace.title || workspace.name || 'Workspace'}`,
+    kind: 'workspace-context',
+    path: context.workspaceImport?.path || '',
+    packagePath: packagePaths[0],
+    packagePaths: Object.freeze(packagePaths),
+    status: 'ready',
+    mode: 'canonical-workspace-context',
+    boundary: context.boundary || 'Canonical workspace context projection for handoff/re-ingest.',
+    context: deepFreeze({ ...context })
+  });
+}
+
+function manifestBlockedEntry(entry = {}) {
+  const path = normalizeRelativePath(entry.path || entry.id || 'blocked-entry');
+  return Object.freeze({
+    id: entry.id || path,
+    title: entry.title || 'Blocked material',
+    kind: entry.kind || 'blocked-material',
+    path,
+    status: 'blocked',
+    reason: entry.reason || 'not-package-ready',
+    boundary: entry.boundary || 'Blocked material is excluded from package entries.'
+  });
+}
+
+export function finalizeExportPackageManifestPaths(manifest = {}, files = []) {
+  const byEntryId = new Map();
+  for (const file of files) {
+    const entryId = String(file.entryId || '');
+    if (!entryId) continue;
+    const current = byEntryId.get(entryId) || [];
+    current.push(String(file.path || ''));
+    byEntryId.set(entryId, current);
+  }
+  const material = manifest.material || {};
+  const remap = (entries = []) => entries.map((entry) => {
+    const paths = byEntryId.get(String(entry.id || '')) || [];
+    return paths.length ? Object.freeze({ ...entry, packagePath: paths[0], packagePaths: Object.freeze(paths.slice()) }) : entry;
+  });
+  const workspaceContext = material.workspaceContext ? (() => {
+    const baseId = String(material.workspaceContext.id || '');
+    const direct = byEntryId.get(baseId) || [];
+    const markdown = byEntryId.get(`${baseId}:markdown`) || [];
+    const paths = [...direct, ...markdown];
+    return paths.length ? Object.freeze({ ...material.workspaceContext, packagePath: paths[0], packagePaths: Object.freeze(paths) }) : material.workspaceContext;
+  })() : null;
+  const nextMaterial = Object.freeze({
+    localDrafts: Object.freeze(remap(material.localDrafts || [])),
+    sourceReferences: Object.freeze(remap(material.sourceReferences || [])),
+    assets: Object.freeze(remap(material.assets || [])),
+    workspaceContextCandidates: Object.freeze(remap(material.workspaceContextCandidates || [])),
+    workspaceContext,
+    blocked: Object.freeze(material.blocked || [])
+  });
+  const fingerprint = exportPackageManifestFingerprint({ ...manifest, material: nextMaterial });
+  const packageId = `package:${safeToken(manifest.packageScope?.workspaceId || manifest.workspaceId || 'workspace')}:${fingerprint}`;
+  return deepFreeze({
+    ...manifest,
+    packageId,
+    material: nextMaterial,
+    integrity: Object.freeze({
+      algorithm: 'tiinex-stable-fingerprint-v1',
+      fingerprint,
+      note: 'Deterministic manifest semantic fingerprint for conformance; durable serialized byte integrity is separately owned by tiinex.package/file-map.json.'
+    })
+  });
+}
+
+function nextActionsForManifest(manifest = {}) {
+  const actions = [];
+  if (manifest.status === 'ready') actions.push('Future export builder may create a package from this manifest.');
+  if (manifest.status === 'degraded') actions.push('Review degraded source references, metadata-only assets, and workspace candidates before package creation.');
+  if (manifest.status === 'blocked') actions.push('Resolve blocked local material or exclude it before package creation.');
+  if ((manifest.counts?.workspaceContextCandidates || 0) > 0) actions.push('Open or merge workspace candidates explicitly if they should become package context.');
+  if ((manifest.counts?.metadataOnlyAssets || 0) > 0) actions.push('Reselect metadata-only assets or accept a degraded metadata-only package entry.');
+  return actions.length ? actions : ['No action required before a future package builder.'];
+}
+
+function manifestFinding(source, item = {}) {
+  return Object.freeze({
+    source,
+    severity: item.severity || 'info',
+    code: item.code || 'finding',
+    message: item.message || String(item.code || 'Finding'),
+    recordId: item.recordId || '',
+    assetId: item.assetId || '',
+    workspaceCandidateId: item.workspaceCandidateId || '',
+    path: item.path || '',
+    repo: item.repo || ''
+  });
+}
+
+function indexByIdAndPath(items = []) {
+  const index = new Map();
+  for (const item of items) {
+    for (const key of [item.id, item.path, item.name, item.title]) {
+      if (key) index.set(String(key), item);
+    }
+  }
+  return index;
+}
+
+function lookupEntry(index, entry = {}) {
+  for (const key of [entry.id, entry.path, entry.title]) {
+    if (key && index.has(String(key))) return index.get(String(key));
+  }
+  return null;
+}
+
+function normalizeRelativePath(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, '_'));
+  }
+  return parts.join('/') || 'entry';
+}
+
+function safeToken(value = '') {
+  return String(value || '').trim().replace(/\\/g, '/').replace(/[^a-zA-Z0-9._/-]+/g, '-').replace(/^[-/.]+|[-/.]+$/g, '').replace(/\/+/, '/').slice(0, 120) || 'unnamed';
+}
+
+function stableFingerprint(value) {
+  const text = typeof value === 'string' ? value : stableStringify(value);
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `tixfp1-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  Object.freeze(value);
+  for (const item of Object.values(value)) deepFreeze(item);
+  return value;
+}

package/src/export/package.preflight.js

@@ -0,0 +1,204 @@
+import { buildPublicationPreflight } from '../publication/publication.preflight.js';
+import { buildReingestPlan } from '../reingest/reingest.plan.js';
+import { buildWorkspaceGovernanceSummary, governanceFindingForBoundary } from '../governance/governance.boundary.js';
+import { buildSourceBoundaryReport, isSourceBacked } from '../diagnostics/sourceBoundary.report.js';
+import { packageAssetBytes } from './package.bytes.js';
+import { projectPackageSourceReference } from './package.sourceReference.js';
+import { buildExportWorkspaceContext } from './package.workspaceContext.js';
+
+export const EXPORT_PACKAGE_PREFLIGHT_SCHEMA_ID = 'tiinex.export.package.preflight.v1';
+
+export function buildExportPackagePreflight(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 workspaceCandidates = Array.isArray(input.workspaceCandidates) ? input.workspaceCandidates : (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []);
+  const sourceBoundary = input.sourceBoundary || buildSourceBoundaryReport(workspace, { records, assets });
+  const publicationPreflight = input.publicationPreflight || buildPublicationPreflight(workspace, { records, assets, workspaceCandidates });
+  const reingestPlan = input.reingestPlan || buildReingestPlan(workspace, { records, assets, workspaceCandidates, sourceBoundary, publicationPreflight });
+  const governanceBoundary = input.governanceBoundary || buildWorkspaceGovernanceSummary(workspace, { records, assets });
+  const findings = [];
+
+  for (const finding of sourceBoundary.findings || []) {
+    if (finding.severity === 'error' || finding.code?.includes('provenance-leak')) findings.push(normalizeFinding('source-boundary', finding));
+  }
+  for (const finding of publicationPreflight.findings || []) {
+    if (finding.severity === 'error' || finding.code?.includes('asset.metadata-only') || finding.code?.includes('workspace-candidate') || finding.code?.includes('source-reference.ref-unpinned')) {
+      findings.push(normalizeFinding('publication-preflight', finding));
+    }
+  }
+  for (const finding of reingestPlan.findings || []) {
+    if (finding.severity === 'error' || finding.code?.includes('metadata-only') || finding.code?.includes('workspace-candidate') || finding.code?.includes('ref-unpinned')) {
+      findings.push(normalizeFinding('reingest-plan', finding));
+    }
+  }
+  for (const boundary of governanceBoundary.sources || []) {
+    const boundaryFinding = governanceFindingForBoundary(boundary);
+    if (boundaryFinding) findings.push(normalizeFinding('governance-boundary', boundaryFinding));
+  }
+
+  const localDraftEntries = (publicationPreflight.publishableLocalDrafts || []).map((record) => localDraftEntry(record));
+  const blockedLocalEntries = (publicationPreflight.blockedLocalDrafts || []).map((record) => blockedLocalEntry(record, findings));
+  const sourceReferenceEntries = (publicationPreflight.sourceReferences || []).map((reference) => sourceReferenceEntry(reference, findings));
+  const assetEntries = assets.map((asset) => assetEntry(asset, findings));
+  const workspaceCandidateEntries = workspaceCandidates.map((candidate) => workspaceCandidateEntry(candidate, findings));
+  const workspaceContext = buildExportWorkspaceContext(workspace, { records, assets });
+
+  if (!localDraftEntries.length && !sourceReferenceEntries.length && !assetEntries.length && !workspaceCandidateEntries.length && !workspaceContext.id && !workspaceContext.workspaceMarkdown?.available) {
+    findings.push(finding('warning', 'export.package.empty', 'No loaded material is available for export/package preflight.', { workspaceId: workspace.id || '' }));
+  }
+
+  const dedupedFindings = prioritizeFindings(dedupeFindings(findings));
+  const counts = {
+    records: records.length,
+    packageEntries: localDraftEntries.length + sourceReferenceEntries.length + assetEntries.length + workspaceCandidateEntries.length + 1,
+    localDraftEntries: localDraftEntries.length,
+    blockedLocalEntries: blockedLocalEntries.length,
+    sourceReferenceEntries: sourceReferenceEntries.length,
+    pinnedSourceReferences: sourceReferenceEntries.filter((entry) => entry.status === 'pinned-reference').length,
+    degradedSourceReferences: sourceReferenceEntries.filter((entry) => entry.status !== 'pinned-reference').length,
+    assetEntries: assetEntries.length,
+    metadataOnlyAssets: assetEntries.filter((entry) => entry.status === 'metadata-only').length,
+    workspaceCandidateEntries: workspaceCandidateEntries.length,
+    workspaceContextEntries: 1,
+    errors: dedupedFindings.filter((item) => item.severity === 'error').length,
+    warnings: dedupedFindings.filter((item) => item.severity === 'warning').length,
+    info: dedupedFindings.filter((item) => item.severity === 'info').length,
+    findings: dedupedFindings.length
+  };
+  const status = counts.errors || counts.blockedLocalEntries ? 'blocked' : (counts.warnings || counts.metadataOnlyAssets || counts.degradedSourceReferences || counts.workspaceCandidateEntries ? 'degraded' : 'ready');
+
+  return Object.freeze({
+    schema: EXPORT_PACKAGE_PREFLIGHT_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    title: `Export package preflight · ${workspace.title || workspace.name || 'workspace'}`,
+    status,
+    boundary: 'Preflight only. It plans a bounded package without creating a zip, mutating sources, or converting local/session material into GitHub provenance.',
+    entryPolicy: 'Embed validated local draft Markdown; preserve source-backed material as explicit source references; keep local assets as assets, never fake leaves.',
+    counts: Object.freeze(counts),
+    governanceBoundary,
+    localDraftEntries: Object.freeze(localDraftEntries),
+    blockedLocalEntries: Object.freeze(blockedLocalEntries),
+    sourceReferenceEntries: Object.freeze(sourceReferenceEntries),
+    assetEntries: Object.freeze(assetEntries),
+    workspaceCandidateEntries: Object.freeze(workspaceCandidateEntries),
+    workspaceContext,
+    findings: Object.freeze(dedupedFindings)
+  });
+}
+
+function localDraftEntry(record = {}) {
+  return Object.freeze({
+    id: record.id || record.path || record.title || '',
+    title: record.title || 'Local draft',
+    path: record.path || '',
+    kind: 'artifact-markdown',
+    status: 'ready',
+    mode: 'embed-local-draft-markdown',
+    boundary: 'Package may embed this validated local draft. It remains a local draft until explicit publication assigns a durable source.'
+  });
+}
+
+function blockedLocalEntry(record = {}, findings = []) {
+  const id = record.id || record.path || record.title || '';
+  findings.push(finding('error', 'export.package.local-entry.blocked', 'Local record is not package-ready; it needs a readable Markdown envelope or an explicit preservation/export policy.', { recordId: id, path: record.path || '' }));
+  return Object.freeze({
+    id,
+    title: record.title || 'Blocked local record',
+    path: record.path || '',
+    kind: 'local-record',
+    status: 'blocked',
+    reason: record.reason || record.status || 'not-package-ready',
+    boundary: 'Blocked local/session material must not be silently packaged as a valid Tiinex leaf.'
+  });
+}
+
+function sourceReferenceEntry(reference = {}, findings = []) {
+  const target = reference.target || projectPackageSourceReference(reference, reference);
+  if (reference.status !== 'pinned-reference' && reference.status !== 'exact-target-reference') {
+    findings.push(finding('warning', 'export.package.source-reference.degraded', 'Source-backed material can be packaged only as a degraded source reference until exact source target authority is explicit.', { recordId: reference.id || '', path: target.path || reference.path || '', repo: target.repo || reference.repo || '' }));
+  }
+  return Object.freeze({
+    id: reference.id || reference.path || reference.title || '',
+    title: reference.title || 'Source reference',
+    path: target.path || reference.path || '',
+    kind: 'source-reference',
+    adapterId: target.adapterId || reference.adapterId || '',
+    repo: target.repo || reference.repo || '',
+    ref: target.ref || reference.ref || '',
+    status: reference.status || target.status || 'degraded-reference',
+    mode: 'preserve-source-reference',
+    target,
+    boundary: 'Package stores exact available source-target authority as a reference; it does not republish or embed it as a new local draft.'
+  });
+}
+
+function assetEntry(asset = {}, findings = []) {
+  const id = asset.id || asset.path || asset.name || '';
+  const sourceBacked = isSourceBacked(asset.source || {});
+  const byteProjection = packageAssetBytes(asset);
+  const hasOwnedBytes = !sourceBacked && byteProjection.bytes.byteLength > 0 && asset.previewState !== 'omitted-large' && asset.cacheState !== 'preview-truncated-for-session-cache';
+  const metadataOnly = !sourceBacked && !hasOwnedBytes;
+  const sourceReference = sourceBacked ? projectPackageSourceReference(asset) : null;
+  if (sourceBacked) {
+    findings.push(finding('info', 'export.package.asset.source-reference', 'Source-backed asset remains an exact/degraded source reference; loaded preview/content bytes are not automatically embedded as owned local bytes.', { assetId: id, path: asset.path || '' }));
+    if (!sourceReference || sourceReference.status === 'degraded-reference') findings.push(finding('warning', 'export.package.asset.source-reference.degraded', 'Source-backed asset lacks exact source-target authority and remains a degraded reference; loaded bytes are still not promoted to owned local content.', { assetId: id, path: asset.path || '' }));
+  } else if (metadataOnly) {
+    findings.push(finding('warning', 'export.package.asset.metadata-only', 'Local asset has no full owned bytes in the loaded session; package must mark it metadata-only or require reselection.', { assetId: id, path: asset.path || '' }));
+  }
+  return Object.freeze({
+    id,
+    title: asset.name || asset.path || 'Asset',
+    path: asset.path || '',
+    kind: 'asset',
+    mediaType: asset.type || asset.mimeType || byteProjection.mediaType || '',
+    byteSize: Number(asset.size || byteProjection.bytes.byteLength || 0),
+    status: sourceBacked ? 'source-reference' : (metadataOnly ? 'metadata-only' : 'content-available'),
+    mode: sourceBacked ? 'asset-source-reference' : (metadataOnly ? 'asset-metadata-entry' : 'asset-content-entry'),
+    sourceReference,
+    boundary: asset.source?.boundary || 'Asset boundary follows its intake source; assets are not fake leaves.'
+  });
+}
+
+function workspaceCandidateEntry(candidate = {}, findings = []) {
+  const id = candidate.id || candidate.path || '';
+  findings.push(finding('info', 'export.package.workspace-candidate.open-merge-required', 'Workspace candidate is context material; it must be explicitly opened or merged before it becomes package entrypoint context.', { workspaceCandidateId: id, path: candidate.path || '' }));
+  return Object.freeze({
+    id,
+    title: candidate.title || candidate.path || 'Workspace candidate',
+    path: candidate.path || '',
+    kind: 'workspace-candidate',
+    status: 'open-or-merge-required',
+    mode: 'context-candidate-reference',
+    boundary: 'Workspace candidate is not packaged as a leaf without explicit open/merge.'
+  });
+}
+
+function normalizeFinding(source, item = {}) {
+  return finding(item.severity || 'info', item.code || 'finding', item.message || String(item.code || 'Finding'), Object.assign({ source }, item.recordId ? { recordId: item.recordId } : {}, item.assetId ? { assetId: item.assetId } : {}, item.workspaceCandidateId ? { workspaceCandidateId: item.workspaceCandidateId } : {}, item.path ? { path: item.path } : {}, item.repo ? { repo: item.repo } : {}));
+}
+
+function prioritizeFindings(items = []) {
+  return items.slice().sort((a, b) => {
+    const aOwn = String(a.code || '').startsWith('export.package') ? 0 : 1;
+    const bOwn = String(b.code || '').startsWith('export.package') ? 0 : 1;
+    if (aOwn !== bOwn) return aOwn - bOwn;
+    const rank = { error: 0, warning: 1, info: 2 };
+    return (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3);
+  });
+}
+
+function dedupeFindings(items = []) {
+  const seen = new Set();
+  const deduped = [];
+  for (const item of items) {
+    const key = [item.severity, item.code, item.recordId || item.assetId || item.workspaceCandidateId || '', item.path || '', item.repo || ''].join('\u0000');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(item);
+  }
+  return deduped;
+}
+
+function finding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra));
+}