@tiinex/core 0.1.1

package/src/tooling/portable/package/material.graph.js

@@ -0,0 +1,236 @@
+import { parsePortableSchemaDocument } from '../schema/schema.contract.js';
+
+export const PORTABLE_MATERIAL_GRAPH_SCHEMA_ID = 'tiinex.portable.material-graph.v1';
+
+export function indexPortableMaterials(materials = []) {
+  const normalized = (Array.isArray(materials) ? materials : []).map((material, index) => normalizeMaterial(material, index));
+  const byKeyCandidates = new Map();
+  const byKey = new Map();
+  const byPath = new Map();
+  const byReference = new Map();
+  for (const material of normalized) {
+    pushIndex(byKeyCandidates, material.representationKey, material);
+    if (material.path) pushIndex(byPath, material.path, material);
+    for (const reference of material.referenceAliases) pushIndex(byReference, reference, material);
+  }
+  const representationKeyConflicts = [];
+  for (const [representationKey, candidates] of byKeyCandidates) {
+    if (candidates.length === 1) byKey.set(representationKey, candidates[0]);
+    else representationKeyConflicts.push(Object.freeze({
+      representationKey,
+      candidates: Object.freeze(candidates.map((material) => Object.freeze({
+        suppliedIndex: material.suppliedIndex,
+        path: material.path,
+        schemaId: material.schemaId,
+        source: material.source
+      })))
+    }));
+  }
+  return Object.freeze({
+    schema: PORTABLE_MATERIAL_GRAPH_SCHEMA_ID,
+    materials: Object.freeze(normalized),
+    byKey,
+    byKeyCandidates,
+    byPath,
+    byReference,
+    representationKeyConflicts: Object.freeze(representationKeyConflicts)
+  });
+}
+
+export function resolvePortableMaterialReference(index = {}, fromMaterial = {}, target = '') {
+  const reference = String(target || '');
+  if (!reference) return resolution('unresolved', [], '', false, 'Reference target is empty.');
+
+  // Absolute references resolve only through exact explicitly supplied aliases.
+  // Relative references are always source-topology relative and must never be
+  // captured first by a repository/global alias with the same text.
+  if (isAbsoluteReference(reference)) {
+    const exact = index.byReference?.get(reference) || [];
+    if (exact.length) return exact.length === 1
+      ? resolution('resolved', exact, reference, false, '')
+      : resolution('ambiguous', exact, reference, false, `Exact reference resolves to ${exact.length} material representations.`);
+    return resolution('unresolved', [], reference, false, 'Absolute reference is not present in the explicitly supplied material graph.');
+  }
+
+  if (!fromMaterial?.path) return resolution('unresolved', [], reference, false, 'Relative reference cannot resolve without a source material path.');
+  const joined = resolveRelativePath(dirname(fromMaterial.path), reference);
+  if (joined.escaped) return resolution('unresolved', [], joined.path, true, 'Relative reference escapes the available path root.');
+  const candidates = index.byPath?.get(joined.path) || [];
+  if (candidates.length === 1) return resolution('resolved', candidates, joined.path, false, '');
+  if (candidates.length > 1) return resolution('ambiguous', candidates, joined.path, false, `Relative reference resolves to ${candidates.length} material representations.`);
+  return resolution('unresolved', [], joined.path, false, 'Relative reference target is not present in the explicitly supplied material graph.');
+}
+
+export function extractQualifiedMarkdownLinkTarget(value = '') {
+  const text = String(value || '');
+  // This is intentionally a decomposition helper, not a shape matcher. Callers must
+  // first prove the scalar matched canonical Machine Shape authority.
+  if (!text.startsWith('[') || !text.endsWith(')')) return '';
+  const separator = text.indexOf('](');
+  if (separator < 1) return '';
+  return text.slice(separator + 2, -1);
+}
+
+
+export function portableFieldDomainOccurrenceQualification(projection = {}, group = '', field = '', value = '', entry = '') {
+  const bucket = (projection.fieldDomains?.groups || []).find((item) => exactToken(item.group) === exactToken(group) && exactToken(item.field) === exactToken(field));
+  if (!bucket) return 'unresolved';
+  const occurrence = (bucket.occurrences || []).find((item) => {
+    if (String(item.value ?? '') !== String(value ?? '')) return false;
+    if (entry && item.owner?.kind === 'declaration') return exactToken(item.owner.entry) === exactToken(entry);
+    return true;
+  });
+  return String(occurrence?.qualification || 'unresolved');
+}
+
+export function normalizePortablePath(value = '') {
+  const text = String(value || '').replace(/\\/g, '/');
+  const absolute = text.startsWith('/');
+  const parts = [];
+  for (const raw of text.split('/')) {
+    const part = raw.trim() === '' ? '' : raw;
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (parts.length && parts.at(-1) !== '..') parts.pop();
+      else if (!absolute) parts.push('..');
+      continue;
+    }
+    parts.push(part);
+  }
+  const joined = parts.join('/');
+  return absolute ? `/${joined}` : joined;
+}
+
+export function dirname(value = '') {
+  const path = normalizePortablePath(value);
+  const index = path.lastIndexOf('/');
+  if (index < 0) return '';
+  if (index === 0) return '/';
+  return path.slice(0, index);
+}
+
+export function pathWithinBoundary(path = '', root = '') {
+  const candidate = normalizePortablePath(path);
+  const boundary = normalizePortablePath(root);
+  if (!boundary) return !candidate.startsWith('..') && !candidate.startsWith('/');
+  return candidate === boundary || candidate.startsWith(`${boundary}/`);
+}
+
+export function relativePathEscapesBoundary(fromMaterial = {}, target = '', boundaryRoot = '') {
+  if (isAbsoluteReference(target)) return false;
+  if (!fromMaterial?.path) return true;
+  const resolved = resolveRelativePath(dirname(fromMaterial.path), target);
+  return resolved.escaped || !pathWithinBoundary(resolved.path, boundaryRoot);
+}
+
+export function isAbsoluteReference(value = '') {
+  const text = String(value || '');
+  const colon = text.indexOf(':');
+  if (colon <= 0) return text.startsWith('//');
+  const scheme = text.slice(0, colon);
+  if (!isAsciiLetter(scheme[0])) return false;
+  for (const char of scheme.slice(1)) {
+    if (!(isAsciiLetter(char) || isAsciiDigit(char) || char === '+' || char === '-' || char === '.')) return false;
+  }
+  return true;
+}
+
+export function materialIsSchemaDocument(material = {}) {
+  return Boolean(material.schemaDocument?.validation?.groups?.length);
+}
+
+export function materialUnderAnyBoundary(material = {}, roots = []) {
+  return (roots || []).some((root) => pathWithinBoundary(material.path, root));
+}
+
+function normalizeMaterial(material = {}, index = 0) {
+  const markdown = String(material.markdown ?? material.content ?? material.text ?? '');
+  const path = normalizePortablePath(material.path || '');
+  const schemaDocument = safeParseSchema(markdown);
+  const explicitKey = String(material.representationId || material.representationKey || material.id || '').trim();
+  const representationKey = explicitKey || `supplied-material:${index}`;
+  const aliases = unique([
+    material.reference,
+    material.url,
+    material.href,
+    material.source?.reference,
+    material.source?.url,
+    material.source?.href
+  ].filter((value) => value !== null && typeof value !== 'undefined' && String(value).trim().length > 0));
+  return Object.freeze({
+    representationKey,
+    path,
+    markdown,
+    schemaId: String(schemaDocument.schemaId || '').trim(),
+    parentSchemaId: String(schemaDocument.parentSchemaId || '').trim(),
+    title: String(schemaDocument.title || '').trim(),
+    schemaDocument,
+    referenceAliases: Object.freeze(aliases),
+    source: Object.freeze(serializableSource(material.source || {})),
+    suppliedIndex: index
+  });
+}
+
+function resolveRelativePath(base = '', target = '') {
+  const targetText = String(target || '').replace(/\\/g, '/');
+  const baseParts = normalizePortablePath(base).split('/').filter(Boolean);
+  const absolute = normalizePortablePath(base).startsWith('/');
+  let escaped = false;
+  for (const part of targetText.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (baseParts.length) baseParts.pop();
+      else escaped = true;
+    } else {
+      baseParts.push(part);
+    }
+  }
+  const path = `${absolute ? '/' : ''}${baseParts.join('/')}`;
+  return { path: normalizePortablePath(path), escaped };
+}
+
+function resolution(qualification, candidates, target, escaped, finding) {
+  return Object.freeze({
+    qualification,
+    target,
+    escaped,
+    candidates: Object.freeze([...(candidates || [])]),
+    finding: String(finding || '')
+  });
+}
+
+function pushIndex(map, key, value) {
+  const token = String(key || '');
+  if (!token) return;
+  if (!map.has(token)) map.set(token, []);
+  map.get(token).push(value);
+}
+
+function safeParseSchema(markdown) {
+  try { return parsePortableSchemaDocument(markdown); } catch { return { validation: { groups: [] }, creation: { groups: [] } }; }
+}
+
+function serializableSource(source = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(source || {})) {
+    if (typeof value === 'function' || typeof value === 'undefined') continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function unique(values = []) {
+  return [...new Set(values.map((value) => String(value || '')).filter(Boolean))];
+}
+
+function exactToken(value = '') { return String(value || '').trim(); }
+
+function isAsciiLetter(char = '') {
+  const code = String(char || '').charCodeAt(0);
+  return (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+}
+
+function isAsciiDigit(char = '') {
+  const code = String(char || '').charCodeAt(0);
+  return code >= 48 && code <= 57;
+}

package/src/tooling/portable/package/runtime.package.js

@@ -0,0 +1,321 @@
+import { buildExportPackageApplyResult, buildExportPackageImportPlan } from '../../../export/package.apply.js';
+import { buildExportPackageBundle, inspectExportPackageBundle } from '../../../export/package.builder.js';
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { packageFileBytes, sha256Hex, stableFingerprintBytes, utf8Text } from '../../../export/package.bytes.js';
+import { EXPORT_PACKAGE_CONTROL_PATHS, exportPackageControlKindForPath } from '../../../export/package.controlTopology.js';
+
+export const PORTABLE_RUNTIME_PACKAGE_SCHEMA_ID = 'tiinex.portable.runtime-package.v1';
+export const PORTABLE_RUNTIME_PACKAGE_ROUNDTRIP_SCHEMA_ID = 'tiinex.portable.runtime-package.roundtrip.v1';
+export const PORTABLE_RUNTIME_PACKAGE_REHYDRATION_SCHEMA_ID = 'tiinex.portable.runtime-package.rehydration.v1';
+
+export function buildPortableRuntimePackage(input = {}, options = {}) {
+  const workspace = portableWorkspace(input);
+  const bundle = buildExportPackageBundle(workspace, {
+    records: workspace.records,
+    assets: workspace.assets,
+    workspaceCandidates: workspace.workspaceMergeCandidates,
+    allowBlocked: input.allowBlocked === true || options.allowBlocked === true,
+    includeDegraded: input.includeDegraded !== false && options.includeDegraded !== false,
+    builtAt: input.builtAt || options.builtAt,
+    clock: options.clock
+  });
+  const findings = [...(bundle.findings || [])];
+  return Object.freeze({
+    schema: PORTABLE_RUNTIME_PACKAGE_SCHEMA_ID,
+    status: bundle.status,
+    workspace: Object.freeze({ id: workspace.id, title: workspace.title, records: workspace.records.length, assets: workspace.assets.length, workspaceCandidates: workspace.workspaceMergeCandidates.length }),
+    bundle,
+    qualification: packageQualification(bundle),
+    findings: Object.freeze(findings),
+    findingSummary: summarizePortableFindings(findings)
+  });
+}
+
+export function inspectPortableRuntimePackage(input = {}) {
+  const bundle = input.bundle || input;
+  const inspection = inspectExportPackageBundle(bundle);
+  return Object.freeze({
+    schema: 'tiinex.portable.runtime-package.inspection.v1',
+    status: inspection.status,
+    inspection,
+    qualification: packageQualification(bundle),
+    findings: inspection.findings,
+    findingSummary: summarizePortableFindings(inspection.findings || [])
+  });
+}
+
+export function rehydratePortableRuntimePackage(input = {}) {
+  const suppliedFiles = Array.isArray(input.files) ? input.files : [];
+  const findings = [];
+  const byPath = new Map(suppliedFiles.map((file) => [normalizePath(file.path || file.name || ''), file]));
+  const manifest = parseJsonContent(byPath.get(EXPORT_PACKAGE_CONTROL_PATHS.manifest));
+  const receipt = parseJsonContent(byPath.get(EXPORT_PACKAGE_CONTROL_PATHS.receipt));
+  const contract = parseJsonContent(byPath.get(EXPORT_PACKAGE_CONTROL_PATHS.contract));
+  const buildReceipt = parseJsonContent(byPath.get(EXPORT_PACKAGE_CONTROL_PATHS.buildReceipt));
+  const fileMap = parseJsonContent(byPath.get(EXPORT_PACKAGE_CONTROL_PATHS.fileMap));
+  if (!manifest) findings.push(portableFinding('error', 'portable.runtime-package.rehydrate.manifest-missing', 'Serialized runtime package files are missing a readable manifest control file.'));
+  const entryIndex = manifestEntryIndex(manifest || {});
+  const fileMapIndex = durableFileMapIndex(fileMap || {});
+  const files = suppliedFiles.map((file) => rehydratedFile(file, entryIndex, fileMapIndex)).filter((file) => file.path);
+  const bundle = Object.freeze({
+    schema: 'tiinex.export.package.bundle.v1',
+    packageId: String(manifest?.packageId || receipt?.packageId || ''),
+    builtAt: String(buildReceipt?.builtAt || receipt?.at || ''),
+    status: String(manifest?.status || 'degraded'),
+    boundary: 'Rehydrated from explicitly supplied serialized package files. No remote fetch, source mutation, or received-code execution occurred.',
+    packageFingerprint: '',
+    packageRepresentationSha256: String(fileMap?.representationSha256 || ''),
+    fileMap: fileMap || null,
+    contract: contract || {},
+    manifest: manifest || {},
+    receipt: receipt || {},
+    buildReceipt: buildReceipt || {},
+    counts: Object.freeze(packageFileCounts(files, findings)),
+    files: Object.freeze(files),
+    findings: Object.freeze(findings)
+  });
+  const inspection = inspectExportPackageBundle(bundle);
+  const combinedFindings = [...findings, ...(inspection.findings || [])];
+  return Object.freeze({
+    schema: PORTABLE_RUNTIME_PACKAGE_REHYDRATION_SCHEMA_ID,
+    status: inspection.status === 'valid' && !combinedFindings.some((finding) => finding.severity === 'error') ? 'rehydrated' : 'invalid',
+    bundle,
+    inspection,
+    qualification: packageQualification(bundle),
+    findings: Object.freeze(combinedFindings),
+    findingSummary: summarizePortableFindings(combinedFindings)
+  });
+}
+
+export function roundTripPortableRuntimePackage(input = {}, options = {}) {
+  const rehydrated = !input.bundle && looksLikeSerializedPackage(input.files) ? rehydratePortableRuntimePackage(input) : null;
+  const built = input.bundle
+    ? Object.freeze({ bundle: input.bundle, status: input.bundle.status, qualification: packageQualification(input.bundle), findings: Object.freeze([]) })
+    : rehydrated
+      ? Object.freeze({ bundle: rehydrated.bundle, status: rehydrated.status, qualification: rehydrated.qualification, findings: rehydrated.findings })
+      : buildPortableRuntimePackage(input, options);
+  const bundle = built.bundle;
+  const inspection = inspectExportPackageBundle(bundle);
+  const importPlan = buildExportPackageImportPlan(bundle, { inspection });
+  const applyResult = buildExportPackageApplyResult(bundle, { importPlan });
+  const findings = [...(built.findings || []), ...(inspection.findings || []), ...(importPlan.findings || [])];
+  const comparisons = compareRoundTrip(bundle, importPlan);
+  findings.push(...comparisons.findings);
+  const errors = findings.filter((finding) => finding.severity === 'error').length;
+  const status = errors ? 'failed' : bundle.status === 'ready' && importPlan.status === 'ready' && comparisons.status === 'match' ? 'passed' : 'passed-degraded';
+  return Object.freeze({
+    schema: PORTABLE_RUNTIME_PACKAGE_ROUNDTRIP_SCHEMA_ID,
+    status,
+    packageId: bundle.packageId || '',
+    bundle,
+    inspection,
+    importPlan,
+    applyResult,
+    comparison: comparisons,
+    qualification: packageQualification(bundle),
+    findings: Object.freeze(findings),
+    findingSummary: summarizePortableFindings(findings)
+  });
+}
+
+function portableWorkspace(input = {}) {
+  const session = input.session || input.snapshot || {};
+  const materials = session.materials || input.materials || input;
+  const staged = input.stagedArtifacts || session.stagedArtifacts || [];
+  const records = dedupeRecords([
+    ...(materials.records || input.records || []),
+    ...staged.map(stagedRecord)
+  ]);
+  const assets = [...(materials.assets || input.assets || [])];
+  const workspaceCandidates = [...(input.workspaceCandidates || input.workspaceMergeCandidates || [])];
+  return Object.freeze({
+    id: String(input.workspaceId || session.workspaceId || 'portable-runtime-package'),
+    name: String(input.name || input.title || input.workspaceTitle || session.workspaceTitle || 'Portable runtime package'),
+    title: String(input.title || input.workspaceTitle || session.workspaceTitle || 'Portable runtime package'),
+    createdAt: String(input.createdAt || session.createdAt || ''),
+    records: Object.freeze(records),
+    assets: Object.freeze(assets),
+    workspaceMergeCandidates: Object.freeze(workspaceCandidates),
+    workspaceMarkdown: String(input.workspaceMarkdown || session.workspaceMarkdown || ''),
+    workspaceImport: Object.freeze({ ...(session.workspaceImport || {}), ...(input.workspaceImport || {}) }),
+    sources: Object.freeze([...(session.sources || input.sources || [])]),
+    sourceOrder: Object.freeze([...(session.sourceOrder || input.sourceOrder || [])]),
+    workspaceMemberBindings: Object.freeze([...(session.workspaceMemberBindings || input.workspaceMemberBindings || [])])
+  });
+}
+
+function stagedRecord(artifact = {}) {
+  return Object.freeze({
+    id: artifact.id || artifact.path,
+    title: artifact.title || titleFromMarkdown(artifact.markdown) || artifact.path || 'Staged artifact',
+    path: artifact.path || 'draft.md',
+    markdown: artifact.markdown || '',
+    schemaId: artifact.schemaId || '',
+    lifecycleStatus: artifact.lifecycleStatus || 'draft',
+    sourceMode: artifact.sourceMode || 'local-portable-staged',
+    source: Object.freeze({
+      kind: 'local-session',
+      adapterId: 'local',
+      path: artifact.path || 'draft.md',
+      boundary: 'Portable staged local artifact; no GitHub provenance inferred.',
+      sourceBacked: false
+    })
+  });
+}
+
+function dedupeRecords(records) {
+  const map = new Map();
+  for (const record of records) {
+    const key = String(record.id || record.path || `${record.title}:${map.size}`);
+    const existing = map.get(key);
+    if (!existing || (String(record.sourceMode || '').startsWith('local-portable-staged') && !String(existing.sourceMode || '').startsWith('local-portable-staged'))) map.set(key, Object.freeze({ ...record }));
+  }
+  return [...map.values()];
+}
+
+function compareRoundTrip(bundle, importPlan) {
+  const findings = [];
+  const artifactFiles = (bundle.files || []).filter((file) => file.kind === 'artifact-markdown');
+  const importedByEntry = new Map((importPlan.records || []).map((record) => [String(record.packageEntryId || '').trim(), record]));
+  for (const file of artifactFiles) {
+    const entryId = String(file.entryId || '').trim();
+    const imported = importedByEntry.get(entryId);
+    if (!imported) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.artifact.missing', 'A governed bundled local artifact did not materialize during import.', { ref: entryId || file.path || '' }));
+    else {
+      const expected = typeof file.content === 'string' ? file.content : utf8Text(packageFileBytes(file));
+      if (String(imported.markdown || '') !== expected) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.artifact.changed', 'A governed bundled local artifact changed during package import.', { ref: entryId || file.path || '' }));
+    }
+  }
+  if ((importPlan.records || []).length !== artifactFiles.length) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.artifact.count', 'Governed local artifact cardinality changed during package import.'));
+  const sourceFiles = (bundle.files || []).filter((file) => file.kind === 'source-reference' || file.kind === 'asset-source-reference');
+  if ((importPlan.sourceReferences || []).length !== sourceFiles.length) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.source-reference.count', 'Source reference cardinality changed during package import.'));
+  const assetFiles = (bundle.files || []).filter((file) => file.kind === 'asset-content' || file.kind === 'asset-metadata');
+  if ((importPlan.assets || []).length !== assetFiles.length) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.asset.count', 'Owned/metadata asset cardinality changed during package import.'));
+  for (const file of assetFiles.filter((item) => item.kind === 'asset-content')) {
+    const asset = (importPlan.assets || []).find((item) => String(item.packageEntryId || '') === String(file.entryId || ''));
+    if (!asset) continue;
+    const expected = packageFileBytes(file);
+    const actual = asset.bytes instanceof Uint8Array ? asset.bytes : packageFileBytes({ content: asset.content || '' });
+    if (expected.byteLength !== actual.byteLength || sha256Hex(expected) !== sha256Hex(actual)) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.asset.changed', 'Owned asset bytes changed during package import.', { ref: file.entryId || file.path || '' }));
+  }
+  if ((importPlan.records || []).some((record) => record.source?.adapterId === 'github')) findings.push(portableFinding('error', 'portable.runtime-package.roundtrip.github-inference', 'Package import incorrectly materialized a local record as GitHub-backed.'));
+  return Object.freeze({
+    schema: 'tiinex.portable.runtime-package.comparison.v2',
+    status: findings.some((finding) => finding.severity === 'error') ? 'mismatch' : 'match',
+    counts: Object.freeze({ artifacts: artifactFiles.length, importedRecords: importPlan.records?.length || 0, sourceReferences: importPlan.sourceReferences?.length || 0, assets: importPlan.assets?.length || 0, workspaceContext: importPlan.counts?.workspaceContext || 0 }),
+    findings: Object.freeze(findings)
+  });
+}
+
+function packageQualification(bundle = {}) {
+  return Object.freeze({
+    sharedRuntimeContract: bundle.schema === 'tiinex.export.package.bundle.v1',
+    runtimeContractId: bundle.schema || 'tiinex.export.package.bundle.v1',
+    canonicalPackageSchemaLocked: false,
+    canonicalHandoffGenerated: true,
+    inMemoryFileMap: true,
+    durableSerializedFileMap: Boolean(bundle.fileMap || (bundle.files || []).some((file) => normalizePath(file.path) === EXPORT_PACKAGE_CONTROL_PATHS.fileMap)),
+    remoteFetch: false,
+    remoteWrite: false,
+    sourceMutation: false,
+    statement: 'Operational Tiinex handoff package with durable representation-level file-map integrity. It is not tiinex.semantic.package.v1 and does not claim semantic ownership or external provenance.'
+  });
+}
+
+function looksLikeSerializedPackage(files = []) {
+  return Array.isArray(files) && files.some((file) => normalizePath(file.path || file.name || '') === EXPORT_PACKAGE_CONTROL_PATHS.manifest);
+}
+
+function parseJsonContent(file = null) {
+  if (!file) return null;
+  try { return JSON.parse(utf8Text(packageFileBytes(file))); }
+  catch { return null; }
+}
+
+function manifestEntryIndex(manifest = {}) {
+  const index = new Map();
+  const groups = [
+    ['localDrafts', 'artifact-markdown'],
+    ['sourceReferences', 'source-reference'],
+    ['assets', 'asset'],
+    ['workspaceContextCandidates', 'workspace-candidate']
+  ];
+  for (const [group, kind] of groups) {
+    for (const entry of manifest.material?.[group] || []) {
+      for (const packagePath of [entry.packagePath, ...(entry.packagePaths || [])].filter(Boolean)) index.set(normalizePath(packagePath), Object.freeze({ ...entry, inferredKind: kind }));
+    }
+  }
+  const context = manifest.material?.workspaceContext;
+  if (context) {
+    for (const packagePath of [context.packagePath, ...(context.packagePaths || [])].filter(Boolean)) index.set(normalizePath(packagePath), Object.freeze({ ...context, inferredKind: packagePath.endsWith('.md') ? 'workspace-context-markdown' : 'workspace-context' }));
+  }
+  return index;
+}
+
+function durableFileMapIndex(fileMap = {}) {
+  const index = new Map();
+  for (const entry of fileMap.entries || []) if (entry?.path) index.set(normalizePath(entry.path), entry);
+  return index;
+}
+
+function rehydratedFile(file = {}, entryIndex = new Map(), fileMapIndex = new Map()) {
+  const path = normalizePath(file.path || file.name || '');
+  const data = packageFileBytes(file);
+  const entry = entryIndex.get(path) || null;
+  const durable = fileMapIndex.get(path) || null;
+  let kind = exportPackageControlKindForPath(path) || durable?.kind || entry?.inferredKind || String(file.kind || 'unknown');
+  if (kind === 'asset') kind = entry?.status === 'source-reference' ? 'asset-source-reference' : entry?.content?.available ? 'asset-content' : 'asset-metadata';
+  const mediaType = String(durable?.mediaType || entry?.mediaType || file.mediaType || file.type || '');
+  const textual = kind.includes('json') || kind.includes('markdown') || /^text\//i.test(mediaType) || /json|markdown/i.test(mediaType);
+  return Object.freeze({
+    path,
+    requestedPath: String(durable?.requestedPath || path),
+    kind,
+    ...(textual ? { content: typeof file.content === 'string' ? file.content : utf8Text(data) } : {}),
+    data,
+    bytes: data.byteLength,
+    sha256: sha256Hex(data),
+    fingerprint: stableFingerprintBytes(data),
+    entryId: String(durable?.entryId || entry?.id || file.entryId || ''),
+    logicalKind: String(durable?.logicalKind || ''),
+    title: String(entry?.title || file.title || ''),
+    mediaType,
+    boundary: String(durable?.boundary || entry?.boundary || file.boundary || ''),
+    sourceBoundary: String(durable?.sourceBoundary || '')
+  });
+}
+
+function packageFileCounts(files = [], findings = []) {
+  return {
+    files: files.length,
+    controlFiles: files.filter((file) => file.path.startsWith('tiinex.package/')).length,
+    materialFiles: files.filter((file) => !file.path.startsWith('tiinex.package/')).length,
+    localDraftFiles: files.filter((file) => file.kind === 'artifact-markdown').length,
+    sourceReferenceFiles: files.filter((file) => file.kind === 'source-reference').length,
+    assetContentFiles: files.filter((file) => file.kind === 'asset-content').length,
+    assetMetadataFiles: files.filter((file) => file.kind === 'asset-metadata').length,
+    assetReferenceFiles: files.filter((file) => file.kind === 'asset-source-reference').length,
+    workspaceContextFiles: files.filter((file) => file.kind === 'workspace-context' || file.kind === 'workspace-context-markdown').length,
+    workspaceCandidateFiles: files.filter((file) => file.kind === 'workspace-candidate').length,
+    errors: findings.filter((finding) => finding.severity === 'error').length,
+    warnings: findings.filter((finding) => finding.severity === 'warning').length,
+    findings: findings.length
+  };
+}
+
+function stableTextFingerprint(value = '') {
+  const text = String(value || '');
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `tixfp1-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+function titleFromMarkdown(markdown = '') {
+  const match = String(markdown || '').match(/^#\s+(.+)$/m);
+  return match?.[1]?.trim() || '';
+}
+
+function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, ''); }