@tiinex/core 0.1.1

package/src/export/package.builder.js

@@ -0,0 +1,366 @@
+import { buildExportPackageContract, buildExportPackageReceipt, finalizeExportPackageManifestPaths } from './package.manifest.js';
+import { packageAssetBytes, packageFileByteView, packageFileBytes, sha256Hex, stableFingerprintBytes, utf8Bytes } from './package.bytes.js';
+import { assignFinalPackagePaths, buildExportPackageFileMap, EXPORT_PACKAGE_FILE_MAP_PATH, finalizeFile, inspectExportPackageFileMap } from './package.fileMap.js';
+import { workspaceContextOwnedMarkdown } from './package.workspaceContext.js';
+import { inspectExportPackageControlConsistency, packageMaterialRepresentationSha256 } from './package.controlIntegrity.js';
+import { buildExportPackageControlIndex, EXPORT_PACKAGE_CONTROL_PATHS, inspectExportPackageControlTopology } from './package.controlTopology.js';
+
+export const EXPORT_PACKAGE_BUNDLE_SCHEMA_ID = 'tiinex.export.package.bundle.v1';
+export const EXPORT_PACKAGE_BUILD_RECEIPT_SCHEMA_ID = 'tiinex.export.package.build.receipt.v1';
+
+export function buildExportPackageBundle(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 initialContract = input.contract || buildExportPackageContract(workspace, Object.assign({}, input, { records, assets, workspaceCandidates }));
+  const initialManifest = initialContract.manifest || {};
+  const builtAt = typeof input.clock === 'function' ? input.clock() : (input.builtAt || new Date().toISOString());
+  const allowBlocked = input.allowBlocked === true;
+  const includeDegraded = input.includeDegraded !== false;
+  const recordIndex = indexByIdAndPath(records);
+  const assetIndex = indexByIdAndPath(assets);
+  const candidateIndex = indexByIdAndPath(workspaceCandidates);
+  const findings = [];
+  const materialFiles = [];
+
+  const blocked = initialManifest.status === 'blocked' && !allowBlocked;
+  if (blocked) {
+    findings.push(bundleFinding('error', 'export.package.bundle.blocked', 'Package bundle was not built because the manifest is blocked.', { packageId: initialManifest.packageId || '' }));
+  } else if (initialManifest.status === 'degraded' && !includeDegraded) {
+    findings.push(bundleFinding('error', 'export.package.bundle.degraded-disabled', 'Package bundle was not built because degraded package entries were not allowed.', { packageId: initialManifest.packageId || '' }));
+  } else {
+    materialFiles.push(...buildLocalDraftFiles(initialManifest.material?.localDrafts || [], recordIndex, findings));
+    materialFiles.push(...buildSourceReferenceFiles(initialManifest.material?.sourceReferences || [], findings));
+    materialFiles.push(...buildAssetFiles(initialManifest.material?.assets || [], assetIndex, findings));
+    materialFiles.push(...buildWorkspaceCandidateFiles(initialManifest.material?.workspaceContextCandidates || [], candidateIndex, findings));
+    materialFiles.push(...buildWorkspaceContextFiles(initialManifest.material?.workspaceContext || {}, workspace, findings));
+  }
+
+  const finalMaterialFiles = assignFinalPackagePaths(materialFiles, findings);
+  const manifest = finalizeExportPackageManifestPaths(initialManifest, finalMaterialFiles);
+  const receipt = buildExportPackageReceipt(manifest, input);
+  const contract = deepFreeze({ ...initialContract, status: manifest.status || initialContract.status || 'unknown', manifest, receipt });
+  const buildReceipt = buildPackageBuildReceipt({ contract, manifest, receipt, builtAt, materialFiles: finalMaterialFiles, findings, blocked });
+  const controlFiles = buildControlFiles({ contract, manifest, receipt, buildReceipt, findings });
+  const governedFiles = assignFinalPackagePaths([...controlFiles, ...finalMaterialFiles], findings).map(finalizeFile);
+  const fileMap = buildExportPackageFileMap(governedFiles, { packageId: manifest.packageId || '' });
+  const fileMapFile = makeJsonFile(EXPORT_PACKAGE_FILE_MAP_PATH, 'package-file-map', fileMap);
+  const files = Object.freeze([...governedFiles, fileMapFile]);
+  const packageFingerprint = stableFingerprint(files.map((file) => ({ path: file.path, fingerprint: file.fingerprint, bytes: file.bytes })));
+  const counts = Object.freeze({
+    files: files.length,
+    controlFiles: files.filter((file) => file.path.startsWith('tiinex.package/')).length,
+    materialFiles: finalMaterialFiles.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,
+    assetReferenceFiles: files.filter((file) => file.kind === 'asset-source-reference').length,
+    assetMetadataFiles: files.filter((file) => file.kind === 'asset-metadata').length,
+    workspaceCandidateFiles: files.filter((file) => file.kind === 'workspace-candidate').length,
+    workspaceContextFiles: files.filter((file) => file.kind === 'workspace-context' || file.kind === 'workspace-context-markdown').length,
+    blocked: manifest.counts?.blocked || 0,
+    errors: findings.filter((finding) => finding.severity === 'error').length,
+    warnings: findings.filter((finding) => finding.severity === 'warning').length,
+    findings: findings.length
+  });
+  const status = counts.errors || blocked ? 'blocked' : (manifest.status === 'degraded' || counts.warnings ? 'degraded' : 'ready');
+
+  return deepFreeze({
+    schema: EXPORT_PACKAGE_BUNDLE_SCHEMA_ID,
+    packageId: manifest.packageId || receipt.packageId || '',
+    builtAt,
+    status,
+    boundary: 'Platform-neutral package representation with durable serialized file-map authority. It writes no zip by itself, mutates no source, fetches no remote content, and preserves local/source/asset/workspace-context boundaries.',
+    packageFingerprint,
+    packageRepresentationSha256: fileMap.representationSha256,
+    contract,
+    manifest,
+    receipt,
+    buildReceipt,
+    fileMap,
+    counts,
+    files,
+    findings: Object.freeze(findings)
+  });
+}
+
+export function inspectExportPackageBundle(bundle = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const paths = new Set();
+  const findings = [];
+  for (const file of files) {
+    if (!file.path) findings.push(bundleFinding('error', 'export.package.bundle.file.path-missing', 'Package file is missing a path.', { kind: file.kind || '' }));
+    if (file.path && paths.has(file.path)) findings.push(bundleFinding('error', 'export.package.bundle.file.path-duplicate', 'Package file path is duplicated.', { path: file.path }));
+    paths.add(file.path);
+    if (file.path && isUnsafePackagePath(file.path)) findings.push(bundleFinding('error', 'export.package.bundle.file.path-unsafe', 'Package file path is unsafe.', { path: file.path }));
+    const data = packageFileByteView(file);
+    if (Number(file.bytes || 0) !== data.byteLength) findings.push(bundleFinding('error', 'export.package.bundle.file.bytes-mismatch', 'Package file byte count does not match exact serialized bytes.', { path: file.path || '' }));
+    if (file.sha256 && file.sha256 !== sha256Hex(data)) findings.push(bundleFinding('error', 'export.package.bundle.file.sha256-mismatch', 'Package file SHA-256 does not match exact serialized bytes.', { path: file.path || '' }));
+    if (file.fingerprint && file.fingerprint !== stableFingerprintBytes(data)) findings.push(bundleFinding('error', 'export.package.bundle.file.fingerprint-mismatch', 'Package file compatibility fingerprint does not match exact serialized bytes.', { path: file.path || '' }));
+  }
+  const controlTopology = inspectExportPackageControlTopology(files);
+  findings.push(...controlTopology.findings);
+  findings.push(...inspectExportPackageControlConsistency(files, { controls: controlTopology.controls, topologyChecked: true }));
+
+  const fileMapFile = files.find((file) => file.path === EXPORT_PACKAGE_CONTROL_PATHS.fileMap);
+  const fileMap = controlTopology.controls.fileMap || parseJsonFile(fileMapFile) || bundle.fileMap || null;
+  if (!fileMap) {
+    findings.push(bundleFinding('error', 'export.package.bundle.file-map-unreadable', 'Package bundle is missing a readable durable file map.'));
+  } else {
+    const manifestFile = files.find((file) => file.path === EXPORT_PACKAGE_CONTROL_PATHS.manifest);
+    const manifest = controlTopology.controls.manifest || parseJsonFile(manifestFile) || bundle.manifest || {};
+    const fileMapInspection = inspectExportPackageFileMap(fileMap, files, manifest);
+    findings.push(...fileMapInspection.findings);
+  }
+  return Object.freeze({
+    schema: 'tiinex.export.package.bundle.inspection.v2',
+    status: findings.some((finding) => finding.severity === 'error') ? 'invalid' : 'valid',
+    counts: Object.freeze({ files: files.length, findings: findings.length, errors: findings.filter((finding) => finding.severity === 'error').length }),
+    findings: Object.freeze(findings)
+  });
+}
+
+function buildControlFiles({ contract, manifest, receipt, buildReceipt, findings }) {
+  const index = buildExportPackageControlIndex({
+    packageId: manifest.packageId || '',
+    status: manifest.status || 'unknown',
+    entries: flattenManifestEntries(manifest)
+  });
+  return [
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.index, 'package-index', index),
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.manifest, 'package-manifest', manifest),
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.receipt, 'package-receipt', receipt),
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.buildReceipt, 'package-build-receipt', buildReceipt),
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.contract, 'package-contract', contract),
+    makeJsonFile(EXPORT_PACKAGE_CONTROL_PATHS.findings, 'package-findings', { schema: 'tiinex.export.package.findings.v1', findings })
+  ];
+}
+
+function buildLocalDraftFiles(entries = [], recordIndex = new Map(), findings = []) {
+  return entries.map((entry) => {
+    const record = lookupEntry(recordIndex, entry) || {};
+    const markdown = record.markdown || record.content || record.text || '';
+    if (!markdown) findings.push(bundleFinding('error', 'export.package.bundle.local-draft.content-missing', 'Local draft manifest entry had no Markdown content to bundle.', { entryId: entry.id || '', path: entry.path || '' }));
+    return makeTextFile(entry.packagePath || `artifacts/${normalizeRelativePath(entry.path || entry.id || 'draft.md')}`, 'artifact-markdown', markdown, {
+      entryId: entry.id || '',
+      logicalKind: 'local-draft',
+      title: entry.title || record.title || '',
+      boundary: entry.boundary || 'Local draft Markdown bundled as local/session material.'
+    });
+  });
+}
+
+function buildSourceReferenceFiles(entries = [], findings = []) {
+  return entries.map((entry) => {
+    if (entry.status === 'degraded-reference') findings.push(bundleFinding('warning', 'export.package.bundle.source-reference.degraded', 'Source reference bundled with degraded exactness; no fallback lookup is attempted.', { entryId: entry.id || '', path: entry.path || '', repo: entry.repo || '' }));
+    const sourceReference = {
+      schema: 'tiinex.export.package.source-reference.v2',
+      id: entry.id || '',
+      title: entry.title || '',
+      status: entry.status || 'degraded-reference',
+      boundary: entry.boundary || 'Source-backed material remains a reference.',
+      target: entry.target || {}
+    };
+    return makeJsonFile(entry.packagePath || `sources/${normalizeRelativePath(entry.id || 'source.source.json')}`, 'source-reference', sourceReference, {
+      entryId: entry.id || '',
+      logicalKind: 'source-reference',
+      sourceBoundary: entry.target?.boundary || ''
+    });
+  });
+}
+
+function buildAssetFiles(entries = [], assetIndex = new Map(), findings = []) {
+  return entries.map((entry) => {
+    const asset = lookupEntry(assetIndex, entry) || {};
+    if (entry.status === 'source-reference') {
+      return makeJsonFile(entry.packagePath, 'asset-source-reference', {
+        schema: 'tiinex.export.package.asset-source-reference.v1',
+        id: entry.id || '',
+        title: entry.title || '',
+        path: entry.path || '',
+        mediaType: entry.mediaType || asset.type || asset.mimeType || '',
+        byteSize: Number(entry.byteSize || asset.size || 0),
+        status: 'source-reference',
+        boundary: entry.boundary || asset.source?.boundary || 'Source-backed asset remains a reference.',
+        target: entry.sourceReference || {}
+      }, { entryId: entry.id || '', logicalKind: 'asset-source-reference', sourceBoundary: entry.sourceReference?.boundary || '' });
+    }
+    if (entry.status === 'content-available') {
+      const projection = packageAssetBytes(asset);
+      if (!projection.bytes.byteLength) findings.push(bundleFinding('error', 'export.package.bundle.asset.content-missing', 'Asset manifest claimed owned content but exact bytes were unavailable.', { entryId: entry.id || '', path: entry.path || '' }));
+      return makeBinaryFile(entry.packagePath, 'asset-content', projection.bytes, {
+        entryId: entry.id || '',
+        logicalKind: 'owned-local-asset',
+        mediaType: entry.mediaType || projection.mediaType || 'application/octet-stream',
+        boundary: entry.boundary || asset.source?.boundary || 'Owned local asset bytes bundled without source promotion.',
+        ...(projection.representation.startsWith('utf8-') ? { content: asset.content || asset.text || '' } : {})
+      });
+    }
+    findings.push(bundleFinding('warning', 'export.package.bundle.asset.metadata-only', 'Local asset bundled as metadata-only descriptor because full owned bytes are unavailable.', { entryId: entry.id || '', path: entry.path || '' }));
+    return makeJsonFile(entry.packagePath, 'asset-metadata', {
+      schema: 'tiinex.export.package.asset-metadata.v2',
+      id: entry.id || '',
+      title: entry.title || '',
+      path: entry.path || '',
+      mediaType: entry.mediaType || asset.type || asset.mimeType || '',
+      size: Number(entry.byteSize || asset.size || 0),
+      status: 'metadata-only',
+      boundary: entry.boundary || asset.source?.boundary || 'Metadata-only local asset entry; content requires reselection.'
+    }, { entryId: entry.id || '', logicalKind: 'asset-metadata' });
+  });
+}
+
+function buildWorkspaceCandidateFiles(entries = [], candidateIndex = new Map(), findings = []) {
+  return entries.map((entry) => {
+    const candidate = lookupEntry(candidateIndex, entry) || {};
+    findings.push(bundleFinding('info', 'export.package.bundle.workspace-candidate.descriptor', 'Legacy/I/O workspace candidate bundled as descriptor only; canonical workspace context is separate.', { entryId: entry.id || '', path: entry.path || '' }));
+    return makeJsonFile(entry.packagePath, 'workspace-candidate', {
+      schema: 'tiinex.export.package.workspace-candidate.v1',
+      id: entry.id || '',
+      title: entry.title || candidate.title || '',
+      path: entry.path || candidate.path || '',
+      status: entry.status || 'open-or-merge-required',
+      boundary: entry.boundary || 'Compatibility workspace candidate descriptor; not canonical runtime workspace context.'
+    }, { entryId: entry.id || '', logicalKind: 'workspace-candidate' });
+  });
+}
+
+function buildWorkspaceContextFiles(entry = {}, workspace = {}, findings = []) {
+  if (!entry.id) return [];
+  const context = entry.context || {};
+  const out = [makeJsonFile(entry.packagePath || 'context/workspace.json', 'workspace-context', context, {
+    entryId: entry.id,
+    logicalKind: 'workspace-context',
+    boundary: entry.boundary || context.boundary || ''
+  })];
+  const markdown = workspaceContextOwnedMarkdown(workspace);
+  if (context.workspaceMarkdown?.available) {
+    if (!markdown) findings.push(bundleFinding('error', 'export.package.bundle.workspace-context.markdown-missing', 'Workspace context claimed owned local workspace Markdown but exact content was unavailable.', { entryId: entry.id }));
+    else out.push(makeTextFile(context.workspaceMarkdown.packagePath || 'context/workspace.workspace.md', 'workspace-context-markdown', markdown, {
+      entryId: `${entry.id}:markdown`,
+      logicalKind: 'workspace-context-markdown',
+      mediaType: 'text/markdown',
+      boundary: 'Owned local workspace artifact/context Markdown. It remains local until explicit publication.'
+    }));
+  }
+  return out;
+}
+
+function buildPackageBuildReceipt({ contract, manifest, receipt, builtAt, materialFiles, findings, blocked }) {
+  const status = blocked || findings.some((finding) => finding.severity === 'error') ? 'blocked' : (manifest.status === 'degraded' || findings.some((finding) => finding.severity === 'warning') ? 'degraded' : 'ready');
+  return Object.freeze({
+    schema: EXPORT_PACKAGE_BUILD_RECEIPT_SCHEMA_ID,
+    packageId: manifest.packageId || receipt.packageId || '',
+    at: builtAt,
+    operation: 'export-package-file-map-built',
+    state: status === 'blocked' ? 'blocked' : 'built-governed-file-map',
+    status,
+    boundary: 'Build receipt records deterministic package material/control construction before ZIP serialization. Exact serialized file bytes are governed by tiinex.package/file-map.json; no remote/source mutation occurred.',
+    manifestFingerprint: manifest.integrity?.fingerprint || '',
+    materialRepresentationSha256: packageMaterialRepresentationSha256(materialFiles),
+    contractStatus: contract.status || manifest.status || 'unknown',
+    counts: Object.freeze({ materialFiles: materialFiles.length, findings: findings.length, errors: findings.filter((finding) => finding.severity === 'error').length, warnings: findings.filter((finding) => finding.severity === 'warning').length }),
+    findings: Object.freeze(findings.slice())
+  });
+}
+
+function flattenManifestEntries(manifest = {}) {
+  const material = manifest.material || {};
+  return [
+    ...(material.localDrafts || []),
+    ...(material.sourceReferences || []),
+    ...(material.assets || []),
+    ...(material.workspaceContextCandidates || []),
+    ...(material.workspaceContext ? [material.workspaceContext] : [])
+  ].map((entry) => ({ id: entry.id || '', kind: entry.kind || '', path: entry.path || '', packagePath: entry.packagePath || '', packagePaths: entry.packagePaths || [], status: entry.status || '' }));
+}
+
+function makeTextFile(path, kind, content, extra = {}) {
+  const text = String(content ?? '');
+  return finalizeFile({
+    path: normalizeRelativePath(path),
+    kind,
+    mediaType: extra.mediaType || (kind.includes('markdown') ? 'text/markdown' : 'text/plain'),
+    content: text,
+    ...omit(extra, ['mediaType'])
+  });
+}
+
+function makeBinaryFile(path, kind, data, extra = {}) {
+  return finalizeFile({
+    path: normalizeRelativePath(path),
+    kind,
+    mediaType: extra.mediaType || 'application/octet-stream',
+    data,
+    ...omit(extra, ['mediaType', 'content']),
+    ...(typeof extra.content === 'string' ? { content: extra.content } : {})
+  });
+}
+
+function makeJsonFile(path, kind, value, extra = {}) {
+  const content = `${stablePrettyJson(value)}\n`;
+  return finalizeFile({
+    path: normalizeRelativePath(path),
+    kind,
+    mediaType: 'application/json',
+    content,
+    ...extra
+  });
+}
+
+function parseJsonFile(file = {}) {
+  try {
+    const data = packageFileBytes(file);
+    return JSON.parse(new TextDecoder().decode(data));
+  } catch (_) {
+    return null;
+  }
+}
+
+function indexByIdAndPath(items = []) {
+  const index = new Map();
+  for (const item of items) {
+    for (const key of [item.id, item.path, item.title, item.name]) 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 === '.' || clean === '..') continue;
+    parts.push(clean.replace(/[\u0000-\u001f<>:"|?*]/g, '_'));
+  }
+  return parts.join('/') || 'entry';
+}
+function isUnsafePackagePath(path = '') { return !path || path.startsWith('/') || path.split('/').includes('..') || /[\\\u0000-\u001f]/.test(path); }
+function stableFingerprint(value) {
+  const text = stableStringify(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 stableStringify(value) { return JSON.stringify(sortForJson(value)); }
+function stablePrettyJson(value) { return JSON.stringify(sortForJson(value), null, 2); }
+function sortForJson(value) {
+  if (Array.isArray(value)) return value.map(sortForJson);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortForJson(value[key])]));
+}
+function omit(object = {}, keys = []) {
+  const out = {};
+  for (const [key, value] of Object.entries(object)) if (!keys.includes(key)) out[key] = value;
+  return out;
+}
+function bundleFinding(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;
+  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.bytes.js

@@ -0,0 +1,164 @@
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+
+export function utf8Bytes(value = '') {
+  return TEXT_ENCODER.encode(String(value ?? ''));
+}
+
+export function utf8Text(value = new Uint8Array()) {
+  return TEXT_DECODER.decode(toUint8Array(value));
+}
+
+export function toUint8Array(value) {
+  if (value instanceof Uint8Array) return value.slice();
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  if (Array.isArray(value) && value.every((item) => Number.isInteger(item) && item >= 0 && item <= 255)) return Uint8Array.from(value);
+  if (value === undefined || value === null) return new Uint8Array();
+  return utf8Bytes(String(value));
+}
+
+export function bytesFromDataUrl(value = '') {
+  const text = String(value || '');
+  const match = text.match(/^data:([^;,]*)(;base64)?,(.*)$/s);
+  if (!match) return null;
+  const mediaType = match[1] || 'text/plain';
+  const base64 = Boolean(match[2]);
+  const payload = match[3] || '';
+  try {
+    const bytes = base64 ? decodeBase64(payload) : utf8Bytes(decodeURIComponent(payload.replace(/\+/g, '%20')));
+    return Object.freeze({ bytes, mediaType });
+  } catch (_) {
+    return null;
+  }
+}
+
+export function packageAssetBytes(asset = {}) {
+  if (asset.bytes instanceof Uint8Array || asset.bytes instanceof ArrayBuffer || ArrayBuffer.isView(asset.bytes) || Array.isArray(asset.bytes)) {
+    return Object.freeze({ bytes: toUint8Array(asset.bytes), mediaType: String(asset.type || asset.mimeType || 'application/octet-stream'), representation: 'raw-bytes' });
+  }
+  if (typeof asset.dataUrl === 'string' && asset.dataUrl) {
+    const decoded = bytesFromDataUrl(asset.dataUrl);
+    if (decoded) return Object.freeze({ bytes: decoded.bytes, mediaType: String(asset.type || asset.mimeType || decoded.mediaType || 'application/octet-stream'), representation: 'decoded-data-url' });
+  }
+  if (typeof asset.content === 'string') return Object.freeze({ bytes: utf8Bytes(asset.content), mediaType: String(asset.type || asset.mimeType || 'text/plain'), representation: 'utf8-content' });
+  if (typeof asset.text === 'string') return Object.freeze({ bytes: utf8Bytes(asset.text), mediaType: String(asset.type || asset.mimeType || 'text/plain'), representation: 'utf8-text' });
+  return Object.freeze({ bytes: new Uint8Array(), mediaType: String(asset.type || asset.mimeType || 'application/octet-stream'), representation: 'unavailable' });
+}
+
+export function packageFileByteView(file = {}) {
+  if (file.data instanceof Uint8Array) return file.data;
+  if (file.bytesData instanceof Uint8Array) return file.bytesData;
+  if (file.bytes instanceof Uint8Array) return file.bytes;
+  return packageFileBytes(file);
+}
+
+export function packageFileBytes(file = {}) {
+  if (file.data instanceof Uint8Array || file.data instanceof ArrayBuffer || ArrayBuffer.isView(file.data) || Array.isArray(file.data)) return toUint8Array(file.data);
+  if (file.bytesData instanceof Uint8Array || file.bytesData instanceof ArrayBuffer || ArrayBuffer.isView(file.bytesData) || Array.isArray(file.bytesData)) return toUint8Array(file.bytesData);
+  if (typeof file.content === 'string') return utf8Bytes(file.content);
+  if (typeof file.markdown === 'string') return utf8Bytes(file.markdown);
+  if (file.bytes instanceof Uint8Array || file.bytes instanceof ArrayBuffer || ArrayBuffer.isView(file.bytes) || Array.isArray(file.bytes)) return toUint8Array(file.bytes);
+  return new Uint8Array();
+}
+
+export function stableFingerprintBytes(value) {
+  const bytes = toUint8Array(value);
+  let hash = 2166136261;
+  for (const byte of bytes) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619);
+  }
+  return `tixfp1-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+export function sha256Hex(value) {
+  const bytes = readOnlyUint8View(value);
+  const words = [];
+  const bitLength = bytes.length * 8;
+  const paddedLength = (((bytes.length + 9 + 63) >> 6) << 6);
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  const high = Math.floor(bitLength / 0x100000000);
+  const low = bitLength >>> 0;
+  view.setUint32(paddedLength - 8, high, false);
+  view.setUint32(paddedLength - 4, low, false);
+
+  let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+  let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+  const w = new Uint32Array(64);
+
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = view.getUint32(offset + i * 4, false);
+    for (let i = 16; i < 64; i += 1) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      // Keep compression-round additions inline. A rest-parameter add helper allocates
+      // per round and turns large recipient-package integrity checks into a CPU hotspot.
+      const temp1 = (h + s1 + ch + K[i] + w[i]) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+      h = g; g = f; f = e; e = (d + temp1) >>> 0;
+      d = c; c = b; b = a; a = (temp1 + temp2) >>> 0;
+    }
+    h0 = (h0 + a) >>> 0; h1 = (h1 + b) >>> 0; h2 = (h2 + c) >>> 0; h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0; h5 = (h5 + f) >>> 0; h6 = (h6 + g) >>> 0; h7 = (h7 + h) >>> 0;
+  }
+  words.push(h0, h1, h2, h3, h4, h5, h6, h7);
+  return words.map((word) => (word >>> 0).toString(16).padStart(8, '0')).join('');
+}
+
+
+function readOnlyUint8View(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (Array.isArray(value) && value.every((item) => Number.isInteger(item) && item >= 0 && item <= 255)) return Uint8Array.from(value);
+  if (value === undefined || value === null) return new Uint8Array();
+  return utf8Bytes(String(value));
+}
+
+function rotr(value, bits) { return (value >>> bits) | (value << (32 - bits)); }
+function decodeBase64(value = '') {
+  const clean = String(value || '').replace(/\s+/g, '');
+  if (typeof atob === 'function') {
+    const binary = atob(clean);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+    return out;
+  }
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let buffer = 0, bits = 0;
+  const out = [];
+  for (const char of clean.replace(/=+$/, '')) {
+    const valueIndex = alphabet.indexOf(char);
+    if (valueIndex < 0) throw new Error('invalid-base64');
+    buffer = (buffer << 6) | valueIndex;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buffer >>> bits) & 0xff);
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+const K = new Uint32Array([
+  0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+  0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+  0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+  0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+  0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+  0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+  0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+  0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2
+]);

package/src/export/package.controlIntegrity.js

@@ -0,0 +1,42 @@
+import { packageFileByteView, packageFileBytes, sha256Hex, utf8Bytes } from './package.bytes.js';
+import { exportPackageManifestFingerprint } from './package.manifest.js';
+import { inspectExportPackageControlTopology } from './package.controlTopology.js';
+
+export function inspectExportPackageControlConsistency(files = [], input = {}) {
+  const topology = input.topologyChecked
+    ? { findings: [], controls: input.controls || {} }
+    : inspectExportPackageControlTopology(files);
+  const findings = [...topology.findings];
+  const manifest = topology.controls.manifest || null;
+  const receipt = topology.controls.receipt || null;
+  const buildReceipt = topology.controls.buildReceipt || null;
+  const contract = topology.controls.contract || null;
+  if (!manifest || !receipt || !buildReceipt || !contract) return findings;
+
+  const expectedFingerprint = exportPackageManifestFingerprint(manifest);
+  if (String(manifest.integrity?.fingerprint || '') !== expectedFingerprint) findings.push(finding('error', 'export.package.bundle.manifest-fingerprint-mismatch', 'Manifest semantic fingerprint does not match its declared material/status authority.'));
+  if (String(receipt.packageId || '') !== String(manifest.packageId || '')) findings.push(finding('error', 'export.package.bundle.receipt-package-id-mismatch', 'Receipt package identity differs from manifest package identity.'));
+  if (String(receipt.manifestFingerprint || '') !== expectedFingerprint) findings.push(finding('error', 'export.package.bundle.receipt-manifest-mismatch', 'Receipt no longer corresponds to the exact manifest semantic fingerprint.'));
+  if (String(buildReceipt.packageId || '') !== String(manifest.packageId || '')) findings.push(finding('error', 'export.package.bundle.build-receipt-package-id-mismatch', 'Build receipt package identity differs from manifest package identity.'));
+  if (String(buildReceipt.manifestFingerprint || '') !== expectedFingerprint) findings.push(finding('error', 'export.package.bundle.build-receipt-manifest-mismatch', 'Build receipt no longer corresponds to the exact manifest semantic fingerprint.'));
+  if (String(buildReceipt.materialRepresentationSha256 || '') !== packageMaterialRepresentationSha256(files)) findings.push(finding('error', 'export.package.bundle.build-receipt-material-mismatch', 'Build receipt no longer corresponds to the exact governed material byte representation.'));
+  if (String(contract.manifest?.integrity?.fingerprint || '') !== expectedFingerprint || String(contract.manifest?.packageId || '') !== String(manifest.packageId || '')) findings.push(finding('error', 'export.package.bundle.contract-manifest-mismatch', 'Embedded contract manifest differs from the serialized manifest control authority.'));
+  if (String(contract.receipt?.manifestFingerprint || '') !== String(receipt.manifestFingerprint || '') || String(contract.receipt?.receiptId || '') !== String(receipt.receiptId || '')) findings.push(finding('error', 'export.package.bundle.contract-receipt-mismatch', 'Embedded contract receipt differs from the serialized receipt control authority.'));
+  return findings;
+}
+
+
+export function packageMaterialRepresentationSha256(files = []) {
+  const entries = files
+    .filter((file) => file?.path && !String(file.path).startsWith('tiinex.package/'))
+    .map((file) => ({
+      path: String(file.path || ''),
+      entryId: String(file.entryId || ''),
+      kind: String(file.kind || ''),
+      bytes: packageFileByteView(file).byteLength,
+      sha256: sha256Hex(packageFileByteView(file))
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path) || a.entryId.localeCompare(b.entryId));
+  return sha256Hex(utf8Bytes(JSON.stringify(entries)));
+}
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }