@tiinex/core 0.1.1

package/src/tooling/portable/handoff/transportCompanion.js

@@ -0,0 +1,175 @@
+import { packageFileBytes } from '../../../export/package.bytes.js';
+
+export const HANDOFF_TRANSPORT_COMPANION_SCHEMA_ID = 'tiinex.portable.handoff-transport-companion-projection.v1';
+export const HANDOFF_TRANSPORT_COMPANION_PATH = 'tiinex.package/handoff-companion.json';
+
+const ACTIONS = Object.freeze({
+  providePackage: 'tiinex.handoff.transport.action.provide-package',
+  invokeRecipient: 'tiinex.handoff.transport.action.invoke-recipient',
+  carryResult: 'tiinex.handoff.transport.action.carry-result'
+});
+
+const KEYS = Object.freeze({
+  providePackage: 'handoff.transport.action.providePackage',
+  invokeRecipient: 'handoff.transport.action.invokeRecipient',
+  carryResult: 'handoff.transport.action.carryResult',
+  invocation: 'handoff.transport.invocation.workspaceArtifact',
+  routingDetail: 'handoff.transport.detail.routing',
+  participationDetail: 'handoff.transport.detail.participation',
+  blockerDetail: 'handoff.transport.detail.blockers'
+});
+
+export function buildHandoffTransportCompanionProjection(input = {}) {
+  const descriptor = input.descriptor || {};
+  const bundle = input.bundle || {};
+  const packageStatus = String(input.packageStatus || descriptor.plan?.status || bundle.status || 'blocked');
+  const routing = qualifyRouting(bundle, descriptor);
+  const participation = qualifyParticipation(input.participation || input.transportParticipation || {});
+  const blockers = [];
+  if (packageStatus === 'blocked') blockers.push(blocker('package-blocked', { packageStatus }));
+  if (routing.state !== 'qualified') blockers.push(blocker(`routing-${routing.state}`, routing.parameters));
+  if (participation.actingRole.state === 'ambiguous') blockers.push(blocker('acting-role-ambiguous', {}));
+  if (participation.actingRole.state === 'unresolved') blockers.push(blocker('acting-role-unresolved', {}));
+  if (participation.actingRole.state === 'invalid') blockers.push(blocker('acting-role-invalid', {}));
+  if (participation.transportPosture.state !== 'qualified') blockers.push(blocker('participation-posture-unqualified', { state: participation.transportPosture.state }));
+  const status = blockers.some((item) => item.id.includes('ambiguous')) ? 'ambiguous' : blockers.length ? 'blocked' : 'ready';
+  const routeParameters = Object.freeze({
+    workspaceId: routing.workspace.id,
+    workspaceTitle: routing.workspace.title,
+    controllingArtifactPath: routing.controllingArtifact.workspaceRelativePath
+  });
+  const actions = Object.freeze([
+    action(ACTIONS.providePackage, KEYS.providePackage, Object.freeze({ packageStatus })),
+    action(ACTIONS.invokeRecipient, KEYS.invokeRecipient, routeParameters),
+    action(ACTIONS.carryResult, KEYS.carryResult, Object.freeze({}))
+  ]);
+  return deepFreeze({
+    schema: HANDOFF_TRANSPORT_COMPANION_SCHEMA_ID,
+    version: 1,
+    boundary: 'non-authoritative-disposable-transport-projection',
+    status,
+    packageState: Object.freeze({ status: packageStatus, descriptorSchema: String(descriptor.schema || '') }),
+    routing,
+    participation,
+    recipientEntrypoint: Object.freeze({
+      kind: 'workspace-artifact-routing',
+      localizationKey: KEYS.invocation,
+      parameters: routeParameters
+    }),
+    actions,
+    progressiveDisclosure: Object.freeze({
+      expertActionIds: Object.freeze(actions.map((item) => item.id)),
+      details: Object.freeze([
+        disclosure('routing', KEYS.routingDetail, routeParameters),
+        disclosure('participation', KEYS.participationDetail, participationParameters(participation)),
+        disclosure('blockers', KEYS.blockerDetail, Object.freeze({ blockerIds: Object.freeze(blockers.map((item) => item.id)) }))
+      ])
+    }),
+    blockers: Object.freeze(blockers),
+    authority: Object.freeze({ semanticAuthority: 'none', carrierEndpointPromotion: false, acceptanceAuthority: false })
+  });
+}
+
+export function inspectHandoffTransportCompanion(bundle = {}) {
+  const findings = [];
+  const projectionFile = (bundle.files || []).find((file) => String(file.path || '') === HANDOFF_TRANSPORT_COMPANION_PATH);
+  const projection = projectionFile ? parseJsonFile(projectionFile) : null;
+  const descriptorFile = (bundle.files || []).find((file) => String(file.path || '') === 'tiinex.package/handoff-closure.json');
+  const descriptor = descriptorFile ? parseJsonFile(descriptorFile) : bundle.handoffClosure || null;
+  if (!projection) findings.push(finding('error', 'portable.handoff-companion.missing', 'Handoff package is missing a readable transport companion projection.'));
+  if (projection && projection.schema !== HANDOFF_TRANSPORT_COMPANION_SCHEMA_ID) findings.push(finding('error', 'portable.handoff-companion.schema.invalid', 'Transport companion projection runtime contract is unsupported.'));
+  if (projection && projection.boundary !== 'non-authoritative-disposable-transport-projection') findings.push(finding('error', 'portable.handoff-companion.boundary.invalid', 'Transport companion projection lost its non-authoritative disposable boundary.'));
+  if (projection && containsCarrierTopology(projection)) findings.push(finding('error', 'portable.handoff-companion.routing.carrier-topology-leak', 'Transport companion exposes disposable package carrier topology as host routing truth.'));
+  if (projection && descriptor) inspectProjectionCorrespondence(projection, descriptor, bundle, findings);
+  const errors = findings.filter((item) => item.severity === 'error').length;
+  return deepFreeze({ schema: 'tiinex.portable.handoff-transport-companion.inspection.v1', status: errors ? 'invalid' : 'valid', projection, findings: Object.freeze(findings), findingSummary: Object.freeze({ findings: findings.length, errors }) });
+}
+
+function qualifyRouting(bundle = {}, descriptor = {}) {
+  const manifest = bundle.manifest || parseJsonFile((bundle.files || []).find((file) => String(file.path || '') === 'tiinex.package/manifest.json')) || {};
+  const workspaceIds = unique([manifest.workspaceId, manifest.packageScope?.workspaceId].filter(Boolean).map(String));
+  const descriptorWorkspaces = descriptor.workspaceMaterializations || [];
+  if (!workspaceIds.length && descriptorWorkspaces.length === 1) workspaceIds.push(String(descriptorWorkspaces[0].id || ''));
+  if (workspaceIds.length !== 1 || !workspaceIds[0]) return routingResult(workspaceIds.length > 1 ? 'ambiguous' : 'unresolved', workspaceIds[0] || '', '', '', { workspaceCandidates: workspaceIds });
+  const workspaceId = workspaceIds[0];
+  const workspaceTitle = String(manifest.packageScope?.workspaceTitle || manifest.title || workspaceId);
+  const artifactPath = controllingArtifactPath(descriptor.handoff || {});
+  if (!artifactPath) return routingResult('unresolved', workspaceId, workspaceTitle, '', { workspaceId, reason: 'controlling-artifact-unqualified' });
+  const workspaceMatches = descriptorWorkspaces.filter((item) => String(item.id || '') === workspaceId);
+  if (descriptorWorkspaces.length && workspaceMatches.length !== 1) return routingResult(workspaceMatches.length > 1 ? 'ambiguous' : 'unresolved', workspaceId, workspaceTitle, artifactPath, { workspaceId, controllingArtifactPath: artifactPath });
+  if (workspaceMatches.length === 1) {
+    const workspace = workspaceMatches[0];
+    if (String(workspace.qualification || '') !== 'qualified' || String(workspace.correlationStatus || '') !== 'qualified') return routingResult('blocked', workspaceId, workspaceTitle, artifactPath, { workspaceId, controllingArtifactPath: artifactPath });
+    const matches = (workspace.includedEntries || []).filter((entry) => normalizeWorkspacePath(entry.path) === artifactPath);
+    if (matches.length !== 1) return routingResult(matches.length > 1 ? 'ambiguous' : 'unresolved', workspaceId, workspaceTitle, artifactPath, { workspaceId, controllingArtifactPath: artifactPath });
+  } else if (!manifestContainsArtifact(manifest, artifactPath)) {
+    return routingResult('unresolved', workspaceId, workspaceTitle, artifactPath, { workspaceId, controllingArtifactPath: artifactPath });
+  }
+  return routingResult('qualified', workspaceId, workspaceTitle, artifactPath, { workspaceId, controllingArtifactPath: artifactPath });
+}
+
+function qualifyParticipation(input = {}) {
+  const posture = String(input.transportPosture || input.posture || 'transport-only');
+  const transportPosture = Object.freeze({ state: posture === 'transport-only' ? 'qualified' : 'unresolved', id: posture });
+  const role = input.actingRole || null;
+  let actingRole = Object.freeze({ state: 'none', schemaId: '', reference: '', label: '' });
+  if (role) {
+    const state = String(role.qualification || role.state || 'unresolved');
+    if (state === 'ambiguous') actingRole = Object.freeze({ state: 'ambiguous', schemaId: '', reference: '', label: '' });
+    else if (state !== 'qualified') actingRole = Object.freeze({ state: 'unresolved', schemaId: String(role.schemaId || ''), reference: '', label: '' });
+    else if (String(role.schemaId || '') !== 'tiinex.party.role.v1' || !exactRoleReference(role.reference)) actingRole = Object.freeze({ state: 'invalid', schemaId: String(role.schemaId || ''), reference: '', label: '' });
+    else actingRole = Object.freeze({ state: 'qualified', schemaId: 'tiinex.party.role.v1', reference: String(role.reference), label: String(role.label || '') });
+  }
+  return deepFreeze({ transportPosture, actingRole, carrierAuthority: 'none', endpointPromotion: false });
+}
+
+function inspectProjectionCorrespondence(projection, descriptor, bundle, findings) {
+  const expected = buildHandoffTransportCompanionProjection({ bundle, descriptor, packageStatus: bundle.status || descriptor.plan?.status || 'blocked', participation: projectionParticipationInput(projection.participation) });
+  if (stableJson(expected.packageState) !== stableJson(projection.packageState)) findings.push(finding('error', 'portable.handoff-companion.package-state.mismatch', 'Transport companion package state diverges from package/closure truth.'));
+  if (stableJson(expected.routing) !== stableJson(projection.routing)) findings.push(finding('error', 'portable.handoff-companion.routing.mismatch', 'Transport companion routing diverges from package/closure truth.'));
+  if (stableJson(expected.participation) !== stableJson(projection.participation)) findings.push(finding('error', 'portable.handoff-companion.participation.mismatch', 'Transport companion participation projection is internally inconsistent.'));
+  if (stableJson(expected.blockers) !== stableJson(projection.blockers)) findings.push(finding('error', 'portable.handoff-companion.blockers.mismatch', 'Transport companion blockers diverge from projected package/routing/participation truth.'));
+  if (String(expected.status) !== String(projection.status)) findings.push(finding('error', 'portable.handoff-companion.status.mismatch', 'Transport companion status diverges from projected blocker truth.'));
+  if (projection.authority?.semanticAuthority !== 'none' || projection.authority?.carrierEndpointPromotion !== false || projection.authority?.acceptanceAuthority !== false) findings.push(finding('error', 'portable.handoff-companion.authority.promotion', 'Transport companion promotes carrier/projection metadata into semantic authority.'));
+}
+
+function projectionParticipationInput(participation = {}) {
+  return { transportPosture: participation.transportPosture?.id || 'transport-only', actingRole: participation.actingRole?.state === 'none' ? null : participation.actingRole };
+}
+function controllingArtifactPath(handoff = {}) {
+  for (const raw of [handoff.id, handoff.path]) {
+    const path = normalizeWorkspacePath(raw);
+    if (isWorkspaceRelativeArtifactPath(path)) return path;
+  }
+  return '';
+}
+function isWorkspaceRelativeArtifactPath(path = '') {
+  if (!path || path.startsWith('/') || path.startsWith('handoff.workspaces/') || path.startsWith('tiinex.package/')) return false;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path) || path.includes('/../') || path.startsWith('../')) return false;
+  return path.includes('/') && /\.trace\.md$/i.test(path);
+}
+function exactRoleReference(value = '') {
+  const ref = String(value || '').trim().replace(/\\/g, '/');
+  return Boolean(ref) && !ref.startsWith('handoff.workspaces/') && !ref.includes('/../') && (ref.endsWith('.trace.md') || /^https:\/\//i.test(ref));
+}
+function manifestContainsArtifact(manifest = {}, artifactPath = '') {
+  const material = manifest.material || {};
+  const entries = [...(material.localDrafts || []), ...(material.sourceReferences || []), ...(material.workspaceArtifacts || [])];
+  return entries.some((entry) => normalizeWorkspacePath(entry.path || entry.sourceArtifactPath) === artifactPath);
+}
+function routingResult(state, id, title, path, parameters) {
+  return deepFreeze({ state, workspace: Object.freeze({ id, title }), controllingArtifact: Object.freeze({ workspaceRelativePath: path }), parameters: Object.freeze(parameters || {}) });
+}
+function participationParameters(participation) { return Object.freeze({ transportPosture: participation.transportPosture.id, actingRoleState: participation.actingRole.state, actingRoleReference: participation.actingRole.reference || '' }); }
+function action(id, localizationKey, parameters) { return Object.freeze({ id, localizationKey, parameters }); }
+function disclosure(id, localizationKey, parameters) { return Object.freeze({ id, localizationKey, parameters }); }
+function blocker(id, parameters) { return Object.freeze({ id: `tiinex.handoff.transport.blocker.${id}`, localizationKey: `handoff.transport.blocker.${camel(id)}`, parameters: Object.freeze(parameters || {}) }); }
+function camel(value = '') { return String(value).replace(/-([a-z])/g, (_, c) => c.toUpperCase()); }
+function normalizeWorkspacePath(value = '') { return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, ''); }
+function unique(values = []) { return [...new Set(values.filter(Boolean))]; }
+function containsCarrierTopology(value) { return stableJson(value).includes('handoff.workspaces/') || stableJson(value).includes('package://handoff.workspaces/'); }
+function parseJsonFile(file = {}) { try { return JSON.parse(new TextDecoder().decode(packageFileBytes(file))); } catch { return null; } }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

package/src/tooling/portable/handoff/workspaceByteProvider.archive.js

@@ -0,0 +1,95 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+
+export function inspectStoredWorkspaceArchiveBytes(bytesInput = new Uint8Array(), normalizeInnerPath = () => Object.freeze({ state: 'invalid', path: '' }), options = {}) {
+  const bytes = options.ownedBytes === true && bytesInput instanceof Uint8Array ? bytesInput : packageFileBytes({ data: bytesInput });
+  const findings = [];
+  const entries = [];
+  if (bytes.byteLength < 22) return deepFreeze({ state: 'invalid', entries: Object.freeze([]), findings: Object.freeze([finding('error', 'portable.handoff-workspace-provider.archive.truncated', 'Workspace archive is too small to be a qualified ZIP representation.')]) });
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  let offset = 0;
+  while (offset + 4 <= bytes.byteLength && view.getUint32(offset, true) === 0x04034b50) {
+    if (offset + 30 > bytes.byteLength) { findings.push(finding('error', 'portable.handoff-workspace-provider.archive.local-header-truncated', 'Workspace archive local header is truncated.')); break; }
+    const flags = view.getUint16(offset + 6, true);
+    const method = view.getUint16(offset + 8, true);
+    const crc = view.getUint32(offset + 14, true);
+    const compressedSize = view.getUint32(offset + 18, true);
+    const uncompressedSize = view.getUint32(offset + 22, true);
+    const nameLength = view.getUint16(offset + 26, true);
+    const extraLength = view.getUint16(offset + 28, true);
+    const nameStart = offset + 30;
+    const dataStart = nameStart + nameLength + extraLength;
+    const dataEnd = dataStart + compressedSize;
+    if (dataEnd > bytes.byteLength) { findings.push(finding('error', 'portable.handoff-workspace-provider.archive.entry-truncated', 'Workspace archive entry bytes exceed archive bounds.')); break; }
+    let rawName = '';
+    try { rawName = decoder.decode(bytes.subarray(nameStart, nameStart + nameLength)); }
+    catch { findings.push(finding('error', 'portable.handoff-workspace-provider.archive.path-utf8-invalid', 'Workspace archive entry name is not valid UTF-8.')); }
+    const normalized = normalizeInnerPath(rawName);
+    if (normalized.state !== 'qualified') findings.push(finding('error', 'portable.handoff-workspace-provider.archive.path-unsafe', 'Workspace archive contains an unsafe inner path.', { path: rawName }));
+    if ((flags & 0x0001) !== 0) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.encrypted-unsupported', 'Encrypted workspace archive entries are unavailable to the qualified provider.', { path: rawName }));
+    if ((flags & 0x0008) !== 0) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.data-descriptor-unsupported', 'Workspace archive data-descriptor entries are unavailable to the deterministic provider.', { path: rawName }));
+    if (method !== 0) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.decoder-unavailable', 'Workspace archive entry codec is unavailable to the package-local stored-ZIP provider.', { path: rawName, method }));
+    if (compressedSize !== uncompressedSize) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.size-shape-invalid', 'Stored workspace archive entry has divergent compressed/uncompressed sizes.', { path: rawName }));
+    const data = bytes.subarray(dataStart, dataEnd);
+    if (method === 0 && crc32(data) !== crc) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.crc-mismatch', 'Workspace archive entry CRC does not match exact carried bytes.', { path: rawName }));
+    entries.push(deepFreeze({ rawPath: rawName, path: normalized.path || rawName, bytes: data.byteLength, sha256: sha256Hex(data), crc32: crc, method, localOffset: offset, data }));
+    offset = dataEnd;
+  }
+  for (const path of duplicates(entries.map((entry) => entry.path))) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.path-duplicate', 'Workspace archive contains duplicate normalized inner paths.', { path }));
+
+  const centralStart = offset;
+  let centralCount = 0;
+  const central = [];
+  while (offset + 4 <= bytes.byteLength && view.getUint32(offset, true) === 0x02014b50) {
+    if (offset + 46 > bytes.byteLength) { findings.push(finding('error', 'portable.handoff-workspace-provider.archive.central-header-truncated', 'Workspace archive central directory is truncated.')); break; }
+    const flags = view.getUint16(offset + 8, true);
+    const method = view.getUint16(offset + 10, true);
+    const crc = view.getUint32(offset + 16, true);
+    const compressedSize = view.getUint32(offset + 20, true);
+    const uncompressedSize = view.getUint32(offset + 24, true);
+    const nameLength = view.getUint16(offset + 28, true);
+    const extraLength = view.getUint16(offset + 30, true);
+    const commentLength = view.getUint16(offset + 32, true);
+    const localOffset = view.getUint32(offset + 42, true);
+    const nameStart = offset + 46;
+    const next = nameStart + nameLength + extraLength + commentLength;
+    if (next > bytes.byteLength) { findings.push(finding('error', 'portable.handoff-workspace-provider.archive.central-entry-truncated', 'Workspace archive central directory entry exceeds archive bounds.')); break; }
+    let rawName = '';
+    try { rawName = decoder.decode(bytes.subarray(nameStart, nameStart + nameLength)); } catch { /* local finding already covers malformed names */ }
+    central.push({ rawName, flags, method, crc, compressedSize, uncompressedSize, localOffset });
+    centralCount += 1;
+    offset = next;
+  }
+  if (offset + 22 > bytes.byteLength || view.getUint32(offset, true) !== 0x06054b50) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.eocd-missing', 'Workspace archive is missing a canonical end-of-central-directory record.'));
+  else qualifyEndRecord({ bytes, view, offset, centralStart, centralCount, entries, findings });
+  if (central.length === entries.length) compareCentralEntries(entries, central, findings);
+  return deepFreeze({ state: findings.some((item) => item.severity === 'error') ? 'invalid' : 'qualified', entries: Object.freeze(entries), findings: Object.freeze(findings) });
+}
+
+function qualifyEndRecord({ bytes, view, offset, centralStart, centralCount, entries, findings }) {
+  const disk = view.getUint16(offset + 4, true);
+  const centralDisk = view.getUint16(offset + 6, true);
+  const entriesDisk = view.getUint16(offset + 8, true);
+  const entriesTotal = view.getUint16(offset + 10, true);
+  const centralSize = view.getUint32(offset + 12, true);
+  const declaredCentralOffset = view.getUint32(offset + 16, true);
+  const commentLength = view.getUint16(offset + 20, true);
+  if (disk !== 0 || centralDisk !== 0 || entriesDisk !== entriesTotal) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.multidisk-unsupported', 'Workspace archive multi-disk topology is unavailable to the package-local provider.'));
+  if (entriesTotal !== entries.length || centralCount !== entries.length) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.entry-count-mismatch', 'Workspace archive local and central entry counts diverge.', { local: entries.length, central: centralCount, declared: entriesTotal }));
+  if (declaredCentralOffset !== centralStart || centralSize !== (offset - centralStart)) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.central-directory-mismatch', 'Workspace archive central-directory location/size diverges from exact bytes.'));
+  if (offset + 22 + commentLength !== bytes.byteLength) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.trailing-bytes', 'Workspace archive contains unqualified trailing bytes after the end record.'));
+}
+
+function compareCentralEntries(entries, central, findings) {
+  for (let index = 0; index < entries.length; index += 1) {
+    const local = entries[index];
+    const item = central[index];
+    if (item.rawName !== local.rawPath || item.method !== local.method || item.crc !== local.crc32 || item.compressedSize !== local.bytes || item.uncompressedSize !== local.bytes || item.localOffset !== local.localOffset) findings.push(finding('error', 'portable.handoff-workspace-provider.archive.central-entry-mismatch', 'Workspace archive central entry diverges from its local-header/byte representation.', { path: local.rawPath }));
+  }
+}
+function duplicates(values = []) { const counts = new Map(); for (const value of values) counts.set(value, (counts.get(value) || 0) + 1); return [...counts.entries()].filter(([, count]) => count > 1).map(([value]) => value); }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ 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); }
+const CRC_TABLE = makeCrcTable();
+function crc32(buffer) { let crc = 0xffffffff; for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8); return (crc ^ 0xffffffff) >>> 0; }
+function makeCrcTable() { const table = new Uint32Array(256); for (let index = 0; index < 256; index += 1) { let value = index; for (let bit = 0; bit < 8; bit += 1) value = (value & 1) ? (0xedb88320 ^ (value >>> 1)) : (value >>> 1); table[index] = value >>> 0; } return table; }

package/src/tooling/portable/handoff/workspaceByteProvider.js

@@ -0,0 +1,271 @@
+import { packageFileBytes, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+import { inspectStoredWorkspaceArchiveBytes } from './workspaceByteProvider.archive.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+
+export const HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID = 'tiinex.portable.handoff-workspace-byte-provider.v1';
+export const HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID = 'tiinex.transport.handoff-workspace-archive-binding.v1';
+export const HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND = 'package-local-stored-zip-v1';
+export const HANDOFF_WORKSPACE_ARCHIVE_CODEC = 'zip-store-v1';
+export const HANDOFF_WORKSPACE_INNER_PATH_NORMALIZATION = 'tiinex.workspace-inner-path.v1';
+
+export function buildHandoffWorkspaceByteProvider(bundle = {}, descriptor = {}) {
+  const workspaceItems = descriptor.workspaceMaterializations || [];
+  const archiveBindings = descriptor.workspaceArchiveBindings || [];
+  const workspaceCounts = countBy(workspaceItems, (item) => String(item.id || ''));
+  const bindingCounts = countBy(archiveBindings, (item) => String(item.workspaceId || ''));
+  const workspaces = [];
+  const findings = [];
+
+  for (const workspace of workspaceItems) {
+    const id = String(workspace.id || '');
+    if (!id) {
+      const provider = blockedWorkspace(workspace, 'exploded', ['workspace-id-unresolved']);
+      workspaces.push(provider);
+      findings.push(providerFinding(provider, 'workspace-id-unresolved'));
+      continue;
+    }
+    if ((workspaceCounts.get(id) || 0) !== 1) {
+      const provider = blockedWorkspace(workspace, 'exploded', ['workspace-id-ambiguous'], 'ambiguous');
+      workspaces.push(provider);
+      findings.push(providerFinding(provider, 'workspace-id-ambiguous'));
+      continue;
+    }
+    const matchingBindings = archiveBindings.filter((item) => String(item.workspaceId || '') === id);
+    let provider;
+    if (matchingBindings.length === 1) provider = qualifyArchiveWorkspace(bundle, workspace, matchingBindings[0]);
+    else if (matchingBindings.length > 1 || (bindingCounts.get(id) || 0) > 1) provider = blockedWorkspace(workspace, 'archive', ['workspace-archive-binding-ambiguous'], 'ambiguous');
+    else provider = qualifyExplodedWorkspace(bundle, workspace);
+    workspaces.push(provider);
+    for (const reason of provider.reasons || []) findings.push(providerFinding(provider, reason));
+  }
+
+  for (const binding of archiveBindings) {
+    const id = String(binding.workspaceId || '');
+    if (!id || !workspaceItems.some((workspace) => String(workspace.id || '') === id)) {
+      findings.push(finding('error', 'portable.handoff-workspace-provider.archive-binding.unbound', 'Workspace/archive binding does not resolve to exactly one descriptor workspace.', { workspaceId: id }));
+    }
+  }
+
+  const status = workspaces.length > 0 && workspaces.every((workspace) => workspace.state === 'qualified') && !findings.some((item) => item.severity === 'error') ? 'ready' : 'blocked';
+  return deepFreeze({
+    schema: HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID,
+    status,
+    workspaces: Object.freeze(workspaces),
+    findings: Object.freeze(dedupeFindings(findings)),
+    boundary: 'Package-local manufacture/material-closure byte provider. Its tiinex.transport.handoff-workspace-archive-binding.v1 descriptor is mechanical transport evidence, not recipient semantic provider authority. Recipient-v2 archive activation separately requires a qualified tiinex.workspace.representation.v1 binding plus its explicit External Payload and exact payload bytes; filename, placement, declaration order, UI state, and path similarity have no semantic authority.'
+  });
+}
+
+export function handoffWorkspaceProviderForId(provider = {}, workspaceId = '') {
+  const matches = (provider.workspaces || []).filter((workspace) => String(workspace.id || '') === String(workspaceId || ''));
+  if (matches.length === 1) return matches[0];
+  return deepFreeze({ state: matches.length > 1 ? 'ambiguous' : 'unresolved', id: String(workspaceId || ''), mode: '', entries: Object.freeze([]), reasons: Object.freeze([matches.length > 1 ? 'workspace-id-ambiguous' : 'workspace-id-unresolved']) });
+}
+
+export function listHandoffWorkspaceEntries(provider = {}, workspaceId = '') {
+  const workspace = handoffWorkspaceProviderForId(provider, workspaceId);
+  return workspace.state === 'qualified' ? workspace.entries || Object.freeze([]) : Object.freeze([]);
+}
+
+export function resolveHandoffWorkspaceEntry(provider = {}, workspaceId = '', innerPath = '') {
+  const workspace = handoffWorkspaceProviderForId(provider, workspaceId);
+  if (workspace.state !== 'qualified') return deepFreeze({ state: workspace.state || 'blocked', reason: (workspace.reasons || [])[0] || 'workspace-provider-unqualified' });
+  const normalized = normalizeHandoffWorkspaceInnerPath(innerPath);
+  if (normalized.state !== 'qualified') return deepFreeze({ state: 'blocked', reason: normalized.reason || 'workspace-inner-path-unsafe' });
+  const matches = (workspace.entries || []).filter((entry) => entry.path === normalized.path);
+  if (matches.length !== 1) return deepFreeze({ state: matches.length > 1 ? 'ambiguous' : 'unresolved', reason: matches.length > 1 ? 'workspace-inner-path-ambiguous' : 'workspace-inner-path-unresolved', workspaceId: workspace.id, workspaceRelativePath: normalized.path });
+  const entry = matches[0];
+  return deepFreeze({
+    state: 'qualified',
+    kind: workspace.mode === 'archive' ? 'workspace-archive-entry' : 'workspace-material',
+    providerMode: workspace.mode,
+    workspaceId: workspace.id,
+    workspaceRelativePath: entry.path,
+    packagePath: String(entry.packagePath || workspace.archive?.packagePath || ''),
+    archivePackagePath: String(entry.archivePackagePath || workspace.archive?.packagePath || ''),
+    innerPath: String(entry.innerPath || entry.path || ''),
+    bytes: Number(entry.bytes || 0),
+    sha256: String(entry.sha256 || ''),
+    data: entry.data,
+    referenceTarget: String(entry.referenceTarget || '')
+  });
+}
+
+export function normalizeHandoffWorkspaceInnerPath(value = '') {
+  const raw = String(value || '');
+  if (!raw || raw.includes('\u0000') || /[\u0000-\u001f]/.test(raw)) return Object.freeze({ state: 'invalid', path: '', reason: 'workspace-inner-path-unsafe' });
+  const slashed = raw.replace(/\\/g, '/');
+  if (slashed.startsWith('/') || slashed.startsWith('//') || /^[A-Za-z]:\//.test(slashed)) return Object.freeze({ state: 'invalid', path: '', reason: 'workspace-inner-path-unsafe' });
+  const parts = [];
+  for (const part of slashed.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') return Object.freeze({ state: 'invalid', path: '', reason: 'workspace-inner-path-traversal' });
+    parts.push(part);
+  }
+  if (!parts.length) return Object.freeze({ state: 'invalid', path: '', reason: 'workspace-inner-path-unsafe' });
+  return Object.freeze({ state: 'qualified', path: parts.join('/'), reason: '' });
+}
+
+export function inspectStoredWorkspaceArchive(bytesInput = new Uint8Array(), options = {}) { return inspectStoredWorkspaceArchiveBytes(bytesInput, normalizeHandoffWorkspaceInnerPath, options); }
+
+function qualifyExplodedWorkspace(bundle, workspace) {
+  const reasons = [];
+  if (String(workspace.qualification || '') !== 'qualified') reasons.push('workspace-qualification-unqualified');
+  if (String(workspace.correlationStatus || '') !== 'qualified') reasons.push('workspace-correlation-unqualified');
+  const entries = [];
+  const seen = new Set();
+  for (const declared of workspace.includedEntries || []) {
+    const normalized = normalizeHandoffWorkspaceInnerPath(declared.path || '');
+    if (normalized.state !== 'qualified') { reasons.push(normalized.reason || 'workspace-inner-path-unsafe'); continue; }
+    if (seen.has(normalized.path)) { reasons.push('workspace-inner-path-duplicate'); continue; }
+    seen.add(normalized.path);
+    const packagePath = String(declared.packagePath || '');
+    const matches = (bundle.files || []).filter((file) => String(file.path || '') === packagePath);
+    if (!packagePath || matches.length !== 1) { reasons.push(matches.length > 1 ? 'workspace-package-path-ambiguous' : 'workspace-package-path-unresolved'); continue; }
+    const data = packageFileBytes(matches[0]);
+    if (Number(declared.bytes || 0) !== data.byteLength) reasons.push('workspace-byte-count-mismatch');
+    if (String(declared.sha256 || '') !== sha256Hex(data)) reasons.push('workspace-byte-digest-mismatch');
+    entries.push(deepFreeze({ path: normalized.path, packagePath, innerPath: normalized.path, bytes: data.byteLength, sha256: sha256Hex(data), referenceTarget: String(declared.referenceTarget || ''), data }));
+  }
+  return deepFreeze({
+    state: reasons.length ? 'blocked' : 'qualified',
+    id: String(workspace.id || ''),
+    title: String(workspace.title || workspace.id || ''),
+    mode: 'exploded',
+    materialization: workspace,
+    entries: Object.freeze(entries),
+    workspaceTarget: null,
+    archive: null,
+    reasons: Object.freeze([...new Set(reasons)]),
+    authority: Object.freeze({ locatorAuthority: false, filenameAuthority: false, packagePlacementAuthority: false })
+  });
+}
+
+function qualifyArchiveWorkspace(bundle, workspace, binding = {}) {
+  const reasons = [];
+  if (String(binding.schema || '') !== HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID) reasons.push('workspace-archive-binding-schema-invalid');
+  if (String(binding.workspaceId || '') !== String(workspace.id || '')) reasons.push('workspace-archive-binding-workspace-id-mismatch');
+  if (String(binding.transportCorrelationKey || '') !== String(workspace.transportCorrelationKey || '')) reasons.push('workspace-archive-binding-stale');
+  const coverage = String(workspace.materialization || '') === 'bounded' ? 'bounded' : String(workspace.materialization || '') === 'complete' ? 'complete' : '';
+  const coverageEvidence = coverage === 'bounded' ? (workspace.scopeEvidence || {}) : (workspace.completenessEvidence || {});
+  if (!coverage || String(workspace.qualification || '') !== 'qualified' || String(coverageEvidence.state || '') !== 'qualified') reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-unqualified' : 'workspace-archive-completeness-unqualified');
+  const expectedRepresentationKind = coverage === 'bounded' ? 'bounded-workspace-snapshot' : 'complete-workspace-snapshot';
+  if (String(binding.coverage || coverage) !== coverage || String(binding.representation?.kind || '') !== expectedRepresentationKind) reasons.push('workspace-archive-representation-kind-invalid');
+  if (String(binding.provider?.kind || '') !== HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND || String(binding.provider?.state || '') !== 'ready') reasons.push('workspace-archive-provider-unavailable');
+  if (String(binding.representation?.codec || '') !== HANDOFF_WORKSPACE_ARCHIVE_CODEC || String(binding.representation?.mediaType || '') !== 'application/zip') reasons.push('workspace-archive-decoder-unavailable');
+  if (String(binding.entryMap?.normalization || '') !== HANDOFF_WORKSPACE_INNER_PATH_NORMALIZATION) reasons.push('workspace-archive-normalization-unqualified');
+
+  const targetPath = String(binding.workspaceTarget?.packagePath || '');
+  const targetFiles = (bundle.files || []).filter((file) => String(file.path || '') === targetPath);
+  const targetData = targetFiles.length === 1 ? packageFileBytes(targetFiles[0]) : new Uint8Array();
+  if (!targetPath || targetFiles.length !== 1) reasons.push(targetFiles.length > 1 ? 'workspace-target-ambiguous' : 'workspace-target-unresolvable');
+  if (targetData.byteLength) {
+    if (Number(binding.workspaceTarget?.bytes || 0) !== targetData.byteLength) reasons.push('workspace-target-byte-count-mismatch');
+    if (String(binding.workspaceTarget?.sha256 || '') !== sha256Hex(targetData)) reasons.push('workspace-target-digest-mismatch');
+  }
+  if (String(binding.workspaceTarget?.schema || '') !== 'tiinex.workspace.v1') reasons.push('workspace-target-schema-binding-invalid');
+
+  const archivePath = String(binding.representation?.packagePath || '');
+  const archiveFiles = (bundle.files || []).filter((file) => String(file.path || '') === archivePath);
+  const archiveData = archiveFiles.length === 1 ? packageFileBytes(archiveFiles[0]) : new Uint8Array();
+  if (!archivePath || archiveFiles.length !== 1) reasons.push(archiveFiles.length > 1 ? 'workspace-archive-locator-ambiguous' : 'workspace-archive-locator-unresolved');
+  if (archiveData.byteLength) {
+    if (Number(binding.representation?.bytes || 0) !== archiveData.byteLength) reasons.push('workspace-archive-byte-count-mismatch');
+    if (String(binding.representation?.digest?.method || '') !== 'sha256') reasons.push('workspace-archive-digest-method-invalid');
+    if (String(binding.representation?.digest?.value || '') !== sha256Hex(archiveData)) reasons.push('workspace-archive-digest-mismatch');
+    if (String(binding.representation?.digest?.target || '') !== 'archive-bytes-as-carried') reasons.push('workspace-archive-digest-target-invalid');
+  }
+
+  const parsedArchive = archiveData.byteLength ? inspectStoredWorkspaceArchive(archiveData, { ownedBytes: true }) : deepFreeze({ state: 'invalid', entries: Object.freeze([]), findings: Object.freeze([]) });
+  if (archiveData.byteLength && parsedArchive.state !== 'qualified') reasons.push(...parsedArchive.findings.map((item) => archiveFindingReason(item.code)));
+  const declaredEntries = normalizeBindingEntries(binding.entryMap?.entries || [], reasons);
+  if (Number(binding.entryMap?.count || 0) !== declaredEntries.length) reasons.push('workspace-archive-entry-map-count-mismatch');
+  if (!sameEntryIdentitySet(declaredEntries, parsedArchive.entries || [])) reasons.push('workspace-archive-entry-map-mismatch');
+  if (!sameEntryIdentitySet(declaredEntries, workspace.includedEntries || [])) reasons.push('workspace-archive-binding-stale');
+
+  const bindingEvidence = coverage === 'bounded' ? (binding.scope || {}) : (binding.completeness || {});
+  if (String(bindingEvidence.state || '') !== 'qualified') reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-unqualified' : 'workspace-archive-completeness-unqualified');
+  if (Number(bindingEvidence.entryCount || 0) !== declaredEntries.length) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-entry-count-mismatch' : 'workspace-archive-completeness-entry-count-mismatch');
+  const totalBytes = declaredEntries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0);
+  if (Number(bindingEvidence.totalBytes || 0) !== totalBytes) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-byte-count-mismatch' : 'workspace-archive-completeness-byte-count-mismatch');
+  if (String(bindingEvidence.entriesFingerprint || '') && String(bindingEvidence.entriesFingerprint || '') !== entrySetFingerprint(declaredEntries)) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-fingerprint-mismatch' : 'workspace-archive-completeness-fingerprint-mismatch');
+  if (String(coverageEvidence.entriesFingerprint || '') && String(coverageEvidence.entriesFingerprint) !== entrySetFingerprint(declaredEntries)) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-evidence-stale' : 'workspace-archive-completeness-evidence-stale');
+  if (Number(coverageEvidence.entryCount || declaredEntries.length) !== declaredEntries.length) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-evidence-stale' : 'workspace-archive-completeness-evidence-stale');
+  if (Number(coverageEvidence.totalBytes || totalBytes) !== totalBytes) reasons.push(coverage === 'bounded' ? 'workspace-archive-bounded-scope-evidence-stale' : 'workspace-archive-completeness-evidence-stale');
+  if (coverage === 'bounded') {
+    if (String(binding.selection?.rule || '') !== 'explicit-binding-per-bounded-scope') reasons.push('workspace-archive-bounded-selection-unqualified');
+    if (String(bindingEvidence.scopeBasis || '') !== 'exact-representation-entry-set' || String(bindingEvidence.includedEntryAuthority || '') !== 'qualified-decoded-entry-set' || String(bindingEvidence.omittedEntryMeaning || '') !== 'outside-representation-not-absent-from-workspace' || String(bindingEvidence.sourceMembershipClaim || '') !== 'represented-entries-are-workspace-relative-source-bytes' || String(bindingEvidence.recoveryClosureBoundary || '') !== 'separate-qualified-closure') reasons.push('workspace-archive-bounded-scope-unqualified');
+  }
+
+  const targetInner = normalizeHandoffWorkspaceInnerPath(binding.workspaceTarget?.innerPath || '');
+  if (targetInner.state !== 'qualified') reasons.push('workspace-target-inner-path-unqualified');
+  const parsedByPath = new Map((parsedArchive.entries || []).map((entry) => [entry.path, entry]));
+  const targetArchiveEntry = targetInner.state === 'qualified' ? parsedByPath.get(targetInner.path) : null;
+  if (!targetArchiveEntry) reasons.push('workspace-target-archive-entry-unresolved');
+  else if (targetData.byteLength && (targetArchiveEntry.bytes !== targetData.byteLength || targetArchiveEntry.sha256 !== sha256Hex(targetData))) reasons.push('workspace-target-archive-entry-mismatch');
+
+  if (targetData.byteLength && targetInner.state === 'qualified') {
+    const targetQualification = qualifyHandoffWorkspaceTarget({ targetPath: targetInner.path, targetData, entries: parsedArchive.entries || [] });
+    if (targetQualification.state !== 'qualified') reasons.push(...(targetQualification.reasons || ['workspace-target-artifact-conformance-unqualified']));
+    const declaredSelfState = String(binding.workspaceTarget?.selfIntegrity?.state || '');
+    if (declaredSelfState !== 'verified') reasons.push('workspace-target-self-integrity-descriptor-unverified');
+    if (declaredSelfState && declaredSelfState !== String(targetQualification.selfIntegrity?.state || '')) reasons.push('workspace-target-self-integrity-stale');
+    if (declaredSelfState === 'verified' && String(binding.workspaceTarget?.selfIntegrity?.value || '') !== String(targetQualification.selfIntegrity?.value || '')) reasons.push('workspace-target-self-integrity-mismatch');
+  }
+
+  const declaredByPath = new Map(declaredEntries.map((entry) => [entry.path, entry]));
+  const runtimeEntries = (parsedArchive.entries || []).map((entry) => {
+    const declared = declaredByPath.get(entry.path) || {};
+    return deepFreeze({ path: entry.path, innerPath: entry.path, archivePackagePath: archivePath, packagePath: archivePath, bytes: entry.bytes, sha256: entry.sha256, referenceTarget: String(declared.referenceTarget || ''), data: entry.data });
+  });
+  return deepFreeze({
+    state: reasons.length ? (reasons.includes('workspace-target-ambiguous') || reasons.includes('workspace-archive-locator-ambiguous') ? 'ambiguous' : 'blocked') : 'qualified',
+    id: String(workspace.id || ''),
+    title: String(workspace.title || workspace.id || ''),
+    mode: 'archive',
+    materialization: workspace,
+    entries: Object.freeze(runtimeEntries),
+    workspaceTarget: deepFreeze({ ...(binding.workspaceTarget || {}), data: targetData }),
+    archive: deepFreeze({ ...(binding.representation || {}), data: archiveData }),
+    binding,
+    reasons: Object.freeze([...new Set(reasons)]),
+    authority: Object.freeze({ locatorAuthority: false, filenameAuthority: false, packagePlacementAuthority: false, bindingAuthority: 'manufacture-material-closure-transport-evidence-only', recipientSemanticActivationAuthority: false })
+  });
+}
+
+function normalizeBindingEntries(entries = [], reasons = []) {
+  const out = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const normalized = normalizeHandoffWorkspaceInnerPath(entry.path || entry.innerPath || '');
+    if (normalized.state !== 'qualified') { reasons.push(normalized.reason || 'workspace-inner-path-unsafe'); continue; }
+    if (seen.has(normalized.path)) { reasons.push('workspace-inner-path-duplicate'); continue; }
+    seen.add(normalized.path);
+    const bytes = Number(entry.bytes || 0);
+    const sha256 = String(entry.sha256 || '');
+    if (bytes < 0 || !/^[0-9a-f]{64}$/i.test(sha256)) reasons.push('workspace-archive-entry-map-identity-invalid');
+    out.push(deepFreeze({ path: normalized.path, bytes, sha256: sha256.toLowerCase(), referenceTarget: String(entry.referenceTarget || '') }));
+  }
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function sameEntryIdentitySet(a = [], b = []) {
+  const left = normalizeEntryIdentitySet(a);
+  const right = normalizeEntryIdentitySet(b);
+  return stableJson(left) === stableJson(right);
+}
+function normalizeEntryIdentitySet(entries = []) {
+  return entries.map((entry) => ({ path: String(entry.path || entry.innerPath || ''), bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || '').toLowerCase(), referenceTarget: String(entry.referenceTarget || '') })).sort((a, b) => a.path.localeCompare(b.path));
+}
+function entrySetFingerprint(entries = []) { return sha256Hex(utf8Bytes(stableJson(normalizeEntryIdentitySet(entries)))); }
+function blockedWorkspace(workspace = {}, mode = '', reasons = [], state = 'blocked') { return deepFreeze({ state, id: String(workspace.id || ''), title: String(workspace.title || workspace.id || ''), mode, materialization: workspace, entries: Object.freeze([]), workspaceTarget: null, archive: null, reasons: Object.freeze(reasons), authority: Object.freeze({ locatorAuthority: false, filenameAuthority: false, packagePlacementAuthority: false }) }); }
+function providerFinding(provider = {}, reason = '') { return finding('error', `portable.handoff-workspace-provider.${String(reason || 'unqualified').replace(/[^a-z0-9.-]+/gi, '-')}`, 'Workspace byte provider could not qualify exact workspace bytes.', { workspaceId: String(provider.id || ''), mode: String(provider.mode || ''), reason }); }
+function archiveFindingReason(code = '') { const suffix = String(code || '').split('.').pop() || 'archive-invalid'; return `workspace-archive-${suffix}`; }
+function countBy(items = [], keyFn) { const out = new Map(); for (const item of items) { const key = keyFn(item); if (key) out.set(key, (out.get(key) || 0) + 1); } return out; }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function dedupeFindings(items = []) { const map = new Map(); for (const item of items) { const key = `${item.severity || ''}:${item.code || ''}:${item.workspaceId || ''}:${item.reason || ''}:${item.path || ''}`; if (!map.has(key)) map.set(key, item); } return [...map.values()]; }
+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); }
+