@tiinex/app 0.1.1

package/src/app/githubSourceOperation.js

@@ -0,0 +1,226 @@
+import { materializeGithubSource } from '../adapters/github/github.adapter.js';
+import { appendImportSummary } from '../workspaces/workspace.import.js';
+import { setWorkspaceDiscoveryProgress, clearWorkspaceDiscoveryProgress } from '../workspaces/workspace.discoveryProgress.js';
+import { stateWithSourceMaterialCleared } from '../workspaces/workspace.sourceMaterial.js';
+import { buildSourceTransportPolicy } from '../sources/transport.policy.js';
+import { clearGithubSourceTextCacheForSource, githubTransportOrderFromTier, normalizeGithubTransportTier } from '../sources/github/github.transport.js';
+import { githubRequestedSurfaces, githubSourceFormState, mergeGithubRequestedSurfaces } from './githubSourceInput.js';
+import { summarizeGithubMaterialization, normalizeRepository } from './githubMaterializationSummary.js';
+import { shouldCommitGithubProgress, yieldForVisibleSourceProgress } from './githubProgress.js';
+import { appConfigMaterializationNotice } from './workspaceContinuityNotices.js';
+import { applyGithubSourceMaterializationCommand } from './githubSourceMaterializationCommand.js';
+import { normalizeExplicitFileRefs } from '@tiinex/core/sources/source.explicitTargets.js';
+
+export async function runGithubSourceOperation(context = {}) {
+  const {
+    input = {},
+    options = {},
+    state,
+    active,
+    runtimeApi,
+    workspaceConfig,
+    githubRequestPending = false,
+    operationRef = { current: { token: null, controller: null } },
+    setNotice = () => {},
+    setDialog = () => {},
+    setGithubRequestPending = () => {},
+    commit = () => {},
+    getLatestState = () => state,
+    fetchImpl = globalThis.fetch?.bind(globalThis),
+    AbortControllerImpl = globalThis.AbortController
+  } = context;
+  const lifecycle = runtimeApi?.lifecycle;
+  const sourceState = options.state || getLatestState() || state;
+  const targetWorkspaceId = options.workspaceId || sourceState?.activeWorkspaceId || active?.id || '';
+  const targetWorkspace = (Array.isArray(sourceState?.workspaces) ? sourceState.workspaces : []).find((workspace) => workspace.id === targetWorkspaceId) || active || null;
+  if (githubRequestPending && input.abortPreviousGithubOperation !== true) { setNotice('GitHub source operation already in progress.'); return { ok: false, error: 'github.operation.pending', state: sourceState }; }
+  if (githubRequestPending && input.abortPreviousGithubOperation === true) try { operationRef.current?.controller?.abort?.(); } catch (_) {}
+  const operationToken = Symbol('github-source-operation'); let operationController = null;
+  const operationIsCurrent = () => !operationController || operationRef.current?.token === operationToken;
+  setGithubRequestPending(true);
+  const { repository, existingSource, sourceId, rootPath, ref, label } = githubSourceFormState(input, targetWorkspace?.sources || [], normalizeRepository);
+  const requestedRef = Object.prototype.hasOwnProperty.call(input, 'ref') ? String(input.ref || '').trim() : String(existingSource?.requestedRef ?? ref).trim();
+  if (!repository) {
+    setNotice('Repo URL or owner/name is required.');
+    setGithubRequestPending(false);
+    return { ok: false, error: 'github.repository.required', state: sourceState };
+  }
+  const registerOnly = input.operation === 'register';
+  let sourceCacheCleared = 0;
+  const transportRefreshTier = normalizeGithubTransportTier(input.transportRefreshTier || input.preferredTransportTier || '');
+  const preferredTransports = transportRefreshTier ? githubTransportOrderFromTier(transportRefreshTier) : null;
+  const transportLabel = preferredTransports ? preferredTransports.join(' → ') : 'cache → mirror → proxy → direct';
+  const explicitFileRefs = normalizeExplicitFileRefs(input.explicitFileRefs ?? input.fileRefs ?? existingSource?.explicitFileRefs ?? existingSource?.config?.explicitFileRefs ?? []);
+  const fileRefs = explicitFileRefs.slice();
+  const selectedTransportSurfaces = Array.isArray(input.transportRefreshSurfaces) ? input.transportRefreshSurfaces.filter(Boolean) : [];
+  const requestedSurfacesForInput = selectedTransportSurfaces.length ? mergeGithubRequestedSurfaces(existingSource?.requestedSurfaces || {}, githubRequestedSurfaces(input, fileRefs), selectedTransportSurfaces) : githubRequestedSurfaces(input, fileRefs);
+  const preservedSourceState = registerOnly && existingSource ? { count: Number(existingSource.count || 0), discoveryState: existingSource.discoveryState, surfaces: existingSource.surfaces, transportOutcome: existingSource.transportOutcome, transportPlan: existingSource.transportPlan, transportTiers: existingSource.transportTiers } : {};
+  const result = lifecycle?.addWorkspaceSource?.(sourceState, targetWorkspaceId, Object.assign({
+    id: sourceId, kind: input.sourceKind || input.kind || 'github-tree', label, repository, ref, requestedRef, rootPath,
+    repoDiscovery: Boolean(input.repoDiscovery), issueDiscovery: Boolean(input.issueDiscovery), issueUrls: input.issueUrls || '', explicitFileRefs,
+    workspaceMatch: input.workspaceMatch || '', appConfigPlan: input.appConfigPlan || '', openBehavior: input.openBehavior || '', preferredDisplay: input.preferredDisplay || '',
+    transportLabel, transportRefreshTier, requestedSurfaces: requestedSurfacesForInput
+  }, preservedSourceState));
+  if (!result?.ok) {
+    setNotice('Could not add GitHub source.');
+    setGithubRequestPending(false);
+    return { ok: false, error: result?.error || 'github.source.add.failed', state: sourceState };
+  }
+  const wantsMaterialization = !registerOnly && Boolean(fileRefs.length || input.repoDiscovery || input.issueDiscovery || input.issueUrls);
+  if (wantsMaterialization && typeof AbortControllerImpl !== 'undefined') { operationController = new AbortControllerImpl(); operationRef.current = { token: operationToken, controller: operationController }; }
+  if (wantsMaterialization && input.resetSourceCache !== false && input.allowSourceCache !== true) sourceCacheCleared = clearGithubSourceTextCacheForSource({ repo: repository });
+  let sourceRegistrationState = result.state;
+  const cleared = wantsMaterialization && input.resetSourceMaterial !== false ? stateWithSourceMaterialCleared(sourceRegistrationState, targetWorkspaceId, result.source.id, { discoveryState: 'loading', surfaces: selectedTransportSurfaces }) : null;
+  if (cleared?.ok) sourceRegistrationState = cleared.state;
+  const selectedOperations = [input.repoDiscovery ? 'repo files discovery' : '', fileRefs.length ? 'explicit file loading' : '', input.issueDiscovery || input.issueUrls ? 'issue snapshot loading' : ''].filter(Boolean);
+  const operationLabel = selectedOperations.length ? selectedOperations.join(' + ') : 'boundary registration';
+  let finalState = sourceRegistrationState;
+  let materializationSourceId = result.source.id;
+  let materializationSourceLabel = result.source.label;
+  let materializationSource = result.source;
+  let noticeMessage = `${result.source.label} source registered. No loading is running; choose Discover on the source to select repo files, explicit files, or issue snapshots.`;
+  const progressCommit = { at: 0, phase: '', percent: -1, label: '' };
+  const publishGithubProgress = (progress = {}) => {
+    if (!operationIsCurrent()) return { ok: false, error: 'github.operation.stale', state: finalState };
+    const progressed = setWorkspaceDiscoveryProgress(finalState, targetWorkspaceId, Object.assign({
+      sourceId: materializationSourceId || result.source.id,
+      phase: 'source-materialization',
+      label: `${materializationSourceLabel} source materialization running`,
+      active: true,
+      quantified: progress.percent != null
+    }, progress));
+    if (progressed?.ok) {
+      finalState = progressed.state;
+      if (shouldCommitGithubProgress(progress, progressCommit)) commit(finalState, 'replace');
+    }
+  };
+  if (!wantsMaterialization) {
+    finalState = appendImportSummary(lifecycle, finalState, {
+      schema: 'tiinex.workspace.import.result.v1',
+      ok: true,
+      message: `${result.source.label}: source boundary registered · no materialization requested.`,
+      counts: { records: 0, assets: 0, workspaceEntries: 0, warnings: 0, errors: 0, previewOmitted: 0 },
+      warnings: [],
+      errors: [],
+      diagnostics: { adapterId: 'github', sourceId: result.source.id, operation: 'register-boundary-only', transport: 'none' }
+    }, {});
+  }
+  if (wantsMaterialization) {
+    finalState = setWorkspaceDiscoveryProgress(finalState, targetWorkspaceId, {
+      sourceId: result.source.id,
+      phase: input.repoDiscovery ? 'repo-discovery' : input.issueDiscovery ? 'issue-snapshots' : 'source-materialization',
+      label: `${result.source.label} accepted · ${operationLabel} via ${transportLabel} transport`,
+      active: true,
+      quantified: false,
+      discoveryState: 'loading'
+    }).state || finalState;
+    setDialog(null);
+    setNotice(`${result.source.label} source registered; loading started.`);
+    commit(finalState, 'push');
+    await yieldForVisibleSourceProgress();
+    try {
+      const transportPolicy = buildSourceTransportPolicy({
+        mode: 'cache-mirror-proxy-direct',
+        maxRequestsPerOperation: Number(input.maxRequestsPerOperation || 550),
+        now: new Date().toISOString(),
+        offline: Boolean(input.offline)
+      });
+      const fetchForOperation = operationController ? (url, init = {}) => fetchImpl(url, Object.assign({}, init || {}, { signal: operationController.signal })) : fetchImpl;
+      const out = await materializeGithubSource(result.source, {
+        fileRefs,
+        repoDiscovery: Boolean(input.repoDiscovery),
+        issueDiscovery: Boolean(input.issueDiscovery),
+        issueUrls: input.issueUrls || '',
+        explicitFileRefs,
+        workspaceMatch: input.workspaceMatch || ''
+      }, { fetchImpl: fetchForOperation, abortSignal: operationController?.signal || null, maxFiles: 500, transportPolicy, workspaceConfig, onProgress: publishGithubProgress, preferredTransports: preferredTransports || undefined, transportOrderExact: Boolean(preferredTransports), allowCache: input.allowSourceCache === true, sourceCacheCleared, hostedRepoMirrorBaseUrls: input.hostedRepoMirrorBaseUrls || [], hostedIssueSnapshotBaseUrls: input.hostedIssueSnapshotBaseUrls || [] });
+      if (!operationIsCurrent()) return { ok: false, error: 'github.operation.stale', state: finalState };
+      const resolvedRef = String(out.diagnostics?.resolvedRef || '').trim();
+      const materializedCommit = String(out.diagnostics?.materializedCommit || '').trim();
+      if ((resolvedRef && !String(result.source.ref || '').trim()) || materializedCommit) {
+        const refined = lifecycle?.addWorkspaceSource?.(finalState, targetWorkspaceId, Object.assign({}, materializationSource, {
+          id: materializationSourceId,
+          repository: materializationSource.repo || repository,
+          repo: materializationSource.repo || repository,
+          ref: String(materializationSource.ref || '').trim() || resolvedRef,
+          requestedRef,
+          materializedCommit,
+          rootPath: materializationSource.rootPath || rootPath,
+          label: materializationSource.label || label,
+          discoveryState: 'deferred',
+          repoDiscovery: Boolean(input.repoDiscovery),
+          issueDiscovery: Boolean(input.issueDiscovery),
+          issueUrls: input.issueUrls || '',
+          explicitFileRefs,
+          workspaceMatch: input.workspaceMatch || '', appConfigPlan: input.appConfigPlan || '', openBehavior: input.openBehavior || '', preferredDisplay: input.preferredDisplay || '',
+          transportRefreshTier,
+          requestedSurfaces: requestedSurfacesForInput
+        }), { sourceIdentityPolicy: 'refine-existing' });
+        if (refined?.ok) {
+          finalState = refined.state;
+          materializationSource = refined.source;
+          materializationSourceId = refined.source.id;
+          materializationSourceLabel = refined.source.label || materializationSourceLabel;
+        }
+      }
+      await yieldForVisibleSourceProgress();
+      const appliedSource = applyGithubSourceMaterializationCommand({
+        lifecycle,
+        state: finalState,
+        workspaceId: targetWorkspaceId,
+        source: materializationSource,
+        sourceId: materializationSourceId,
+        sourceLabel: materializationSourceLabel,
+        adapterResult: out,
+        repository,
+        ref: String(materializationSource.ref || '').trim() || resolvedRef || ref,
+        requestedRef,
+        materializedCommit,
+        rootPath,
+        repoDiscovery: Boolean(input.repoDiscovery),
+        issueDiscovery: Boolean(input.issueDiscovery),
+        issueUrls: input.issueUrls || '',
+        explicitFileRefs,
+        workspaceMatch: input.workspaceMatch || '',
+        appConfigPlan: input.appConfigPlan || '',
+        openBehavior: input.openBehavior || '',
+        preferredDisplay: input.preferredDisplay || '',
+        requestedSurfaces: requestedSurfacesForInput,
+        selectedTransportSurfaces,
+        existingSource,
+        transportLabel,
+        transportRefreshTier,
+        preserveView: Boolean(input.preserveView)
+      });
+      if (appliedSource?.ok) finalState = appliedSource.state;
+      noticeMessage = appConfigMaterializationNotice(input, materializationSourceLabel, summarizeGithubMaterialization(materializationSourceLabel, out));
+    } catch (e) {
+      if (!operationIsCurrent()) return { ok: false, error: 'github.operation.stale', state: finalState };
+      console.error(e);
+      finalState = setWorkspaceDiscoveryProgress(finalState, targetWorkspaceId, {
+        sourceId: result.source.id,
+        phase: 'failed',
+        label: `${materializationSourceLabel} materialization failed`,
+        percent: 100,
+        active: false
+      }).state || finalState;
+      noticeMessage = `${materializationSourceLabel} source registered; source materialization failed.`;
+    }
+    finalState = clearWorkspaceDiscoveryProgress(finalState, targetWorkspaceId, '').state || finalState;
+  }
+  if (!operationIsCurrent()) return { ok: false, error: 'github.operation.stale', state: finalState };
+  if (operationController && operationIsCurrent()) operationRef.current = { token: null, controller: null };
+  setDialog(null);
+  setNotice(noticeMessage);
+  setGithubRequestPending(false);
+  commit(finalState, 'push');
+  return { ok: true, state: finalState, sourceId: materializationSourceId };
+}
+
+export function abortGithubSourceOperation(operationRef = { current: null }) {
+  try { operationRef.current?.controller?.abort?.(); } catch (_) {}
+}
+
+export function clearGithubSourceCacheForSource(source = {}) {
+  return clearGithubSourceTextCacheForSource(source);
+}

package/src/app/governanceDialogData.js

@@ -0,0 +1,27 @@
+import { buildGovernanceBoundaryForSource } from '@tiinex/core/governance/governance.boundary.js';
+import { readGithubCachedTextForSourcePath } from '../sources/github/github.transport.js';
+
+export function sourceGovernanceDialogData(source = {}, workspace = {}, env = {}) {
+  const boundary = source.governanceBoundary?.schema
+    ? source.governanceBoundary
+    : buildGovernanceBoundaryForSource(source, {
+        records: (workspace.records || []).filter((record) => String(record?.source?.id || '') === String(source.id || '')),
+        assets: (workspace.assets || []).filter((asset) => String(asset?.source?.id || '') === String(source.id || '')),
+        rootChecked: false,
+        discoveredFrom: 'source-governance-dialog'
+      });
+  const storage = env.storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  const documents = [boundary?.policy, boundary?.notice]
+    .filter((item) => item && item.path)
+    .map((file) => {
+      const cached = readGithubCachedTextForSourcePath(source, file.path, { storage });
+      return {
+        kind: file.kind || file.path,
+        path: file.path,
+        url: file.url || cached?.url || '',
+        markdown: cached?.body || '',
+        cacheState: cached?.cache ? `source-cache:${cached.cache}` : (file.contentAvailable ? 'content-not-in-route-state' : 'metadata-only')
+      };
+    });
+  return { boundary, documents };
+}

package/src/app/handoffPackageImportCommand.js

@@ -0,0 +1,182 @@
+import { fileToArchiveDecodedEntries, qualifyDecodedArchiveEntries } from '@tiinex/core/adapters/archive/archive.adapter.js';
+import { EXPORT_PACKAGE_CONTROL_ROLES } from '@tiinex/core/export/package.controlTopology.js';
+import { buildExportPackageApplyResult, buildExportPackageImportPlan } from '@tiinex/core/export/package.apply.js';
+import { rehydratePortableRuntimePackage } from '@tiinex/core/tooling/portable/package/runtime.package.js';
+
+const KNOWN_CONTROL_PATHS = new Set(EXPORT_PACKAGE_CONTROL_ROLES.map((entry) => entry.path));
+
+export async function tryReadOperationalHandoffPackage(files = [], options = {}) {
+  const selected = Array.from(files || []).filter(Boolean);
+  if (selected.length !== 1 || !/\.zip$/i.test(String(selected[0]?.name || selected[0]?.relativePath || ''))) return Object.freeze({ detected: false });
+  let decoded;
+  try {
+    decoded = options.predecodedArchive || await fileToArchiveDecodedEntries(selected[0], { ...options, source: 'handoff-package-intake' });
+  } catch (error) {
+    return Object.freeze({ detected: false, extractionError: error });
+  }
+  const controlPaths = (decoded.entries || []).map((entry) => String(entry.path || '')).filter((path) => KNOWN_CONTROL_PATHS.has(path));
+  const packagePrefixCount = (decoded.entries || []).filter((entry) => String(entry.path || '').startsWith('tiinex.package/')).length;
+  const detected = controlPaths.length >= 2 || (controlPaths.length >= 1 && packagePrefixCount >= 3);
+  if (!detected) return Object.freeze({ detected: false, extracted: decoded });
+
+  const extracted = await qualifyDecodedArchiveEntries(decoded, { ...options, source: 'handoff-package-intake', stripPortableControl: false, enforceMergePreflight: false });
+  if ((extracted.errors || []).length) return Object.freeze({ detected: true, ok: false, error: 'handoff-package.archive-read-failed', extracted, notice: 'Claimed Handoff package could not be read safely.' });
+
+  const rehydrated = rehydratePortableRuntimePackage({ files: extracted.entries || [] });
+  if (rehydrated.status !== 'rehydrated' || rehydrated.inspection?.status !== 'valid') {
+    return Object.freeze({ detected: true, ok: false, error: 'handoff-package.invalid', extracted, rehydrated, notice: firstFinding(rehydrated.findings) || 'Claimed Handoff package failed package inspection.' });
+  }
+  const importPlan = buildExportPackageImportPlan(rehydrated.bundle, { inspection: rehydrated.inspection });
+  const applyResult = buildExportPackageApplyResult(rehydrated.bundle, { importPlan });
+  if (importPlan.status === 'blocked' || applyResult.status === 'blocked') {
+    return Object.freeze({ detected: true, ok: false, error: 'handoff-package.import-blocked', extracted, rehydrated, importPlan, applyResult, notice: firstFinding(importPlan.findings) || 'Handoff package import is blocked.' });
+  }
+  return Object.freeze({
+    detected: true,
+    ok: true,
+    extracted,
+    rehydrated,
+    importPlan,
+    applyResult,
+    boundary: 'Exact operational Handoff package intake. One archive decode owner feeds bounded package detection; shared rehydration/inspection/import/apply own package interpretation; Site only applies qualified outputs through workspace lifecycle.'
+  });
+}
+
+export function applyOperationalHandoffPackageToWorkspace(input = {}) {
+  const lifecycle = input.lifecycle;
+  const state = input.state;
+  const handoff = input.handoff;
+  const options = input.options || {};
+  if (!lifecycle || !handoff?.ok) return { ok: false, error: 'handoff-package.apply.input-invalid', state, notice: 'Handoff package could not be applied.' };
+  const plan = handoff.importPlan || {};
+  const adapterResult = handoff.applyResult?.adapterResult || {};
+  const context = plan.workspaceContext || {};
+  const workspaceEntry = (adapterResult.workspaceEntries || [])[0] || null;
+  const requestedWorkspaceId = uniqueHandoffWorkspaceId(state, String(context.id || '').trim(), String(plan.packageId || '').trim());
+
+  let opened;
+  if (workspaceEntry?.markdown && lifecycle.openWorkspaceFromMarkdown) {
+    opened = lifecycle.openWorkspaceFromMarkdown(state, workspaceEntry.markdown, {
+      id: requestedWorkspaceId || undefined,
+      title: context.title || context.name || workspaceEntry.title || 'Imported handoff',
+      path: workspaceEntry.path || context.workspaceImport?.path || 'workspace.workspace.md',
+      sourceMode: 'package-import-workspace-file'
+    }, options);
+  } else if (lifecycle.createWorkspace) {
+    opened = lifecycle.createWorkspace(state, { id: requestedWorkspaceId || undefined, name: context.title || context.name || 'Imported handoff' }, options);
+  }
+  if (!opened?.ok) return { ok: false, error: opened?.error || 'handoff-package.workspace-open-failed', state, handoff, notice: 'Could not create the Handoff workspace through the canonical lifecycle.' };
+
+  let nextState = opened.state;
+  let workspaceId = opened.workspace?.id || context.id || '';
+  const recordResult = (adapterResult.records || []).length ? lifecycle.addWorkspaceRecords?.(nextState, workspaceId, adapterResult.records, options) : null;
+  if (recordResult?.ok) nextState = recordResult.state;
+  else if ((adapterResult.records || []).length) return { ok: false, error: recordResult?.error || 'handoff-package.records-apply-failed', state, handoff, notice: 'Could not restore Handoff local artifacts.' };
+
+  const sourceRows = (Array.isArray(context.sources) ? context.sources : []).filter((source) => source && source.id !== 'local' && source.adapterId);
+  for (const source of sourceRows) {
+    const registered = lifecycle.addWorkspaceSource?.(nextState, workspaceId, {
+      id: source.id,
+      label: source.label,
+      adapterId: source.adapterId,
+      sourceKind: source.sourceKind,
+      repository: source.repo,
+      ref: source.ref,
+      requestedRef: source.requestedRef,
+      materializedCommit: source.materializedCommit,
+      rootPath: source.rootPath,
+      boundary: source.boundary,
+      repoDiscovery: source.repoDiscovery,
+      issueDiscovery: source.issueDiscovery,
+      issueUrls: source.issueUrls,
+      explicitFileRefs: source.explicitFileRefs,
+      discoveryState: 'deferred'
+    }, { ...options, sourceIdentityPolicy: 'refine-existing' });
+    if (registered?.ok) nextState = registered.state;
+  }
+
+  // Shared package apply returns exact binary Uint8Array values, while current workspace lifecycle/persistence is JSON-shaped.
+  // Normalize only the Site-local asset representation to byte arrays so exact bytes survive later clone/persistence/reopen;
+  // shared package byte owners already accept arrays on subsequent export.
+  const localAssets = (adapterResult.assets || []).map(jsonSafePackageAsset);
+  const assetResult = localAssets.length ? lifecycle.addWorkspaceAssets?.(nextState, workspaceId, localAssets, options) : null;
+  if (assetResult?.ok) nextState = assetResult.state;
+  else if (localAssets.length) return { ok: false, error: assetResult?.error || 'handoff-package.assets-apply-failed', state, handoff, notice: 'Could not restore Handoff local assets.' };
+
+  const next = nextState;
+  const workspace = (next.workspaces || []).find((item) => item.id === workspaceId) || lifecycle.activeWorkspace?.(next);
+  if (!workspace) return { ok: false, error: 'handoff-package.workspace-missing-after-apply', state, handoff, notice: 'Handoff workspace disappeared during import.' };
+  workspaceId = workspace.id;
+  workspace.workspaceImport = Object.assign({}, workspace.workspaceImport || {}, {
+    schema: 'tiinex.workspace.import.v1',
+    sourceMode: 'package-import-workspace-file',
+    boundary: 'browser-local Handoff package import; package source references remain reference-only descriptors',
+    handoffPackageId: plan.packageId || '',
+    handoffPackageRepresentationSha256: plan.fileMap?.representationSha256 || '',
+    packageSourceReferences: (plan.sourceReferences || []).map(compactSourceReference)
+  });
+  workspace.workspaceMemberBindings = Array.isArray(context.workspaceMemberBindings) ? context.workspaceMemberBindings.map((binding) => structuredCloneSafe(binding)) : (workspace.workspaceMemberBindings || []);
+  const desiredSourceOrder = ['local', ...(Array.isArray(context.sourceOrder) ? context.sourceOrder : []).filter((id) => id && id !== 'local')];
+  workspace.sourceOrder = [...new Set([...desiredSourceOrder.filter((id) => (workspace.sources || []).some((source) => source.id === id)), ...(workspace.sources || []).map((source) => source.id)])];
+  workspace.packageWorkspaceContext = compactWorkspaceContext(context);
+  workspace.importResults = Array.isArray(workspace.importResults) ? workspace.importResults.slice() : [];
+  workspace.importResults.unshift({
+    schema: 'tiinex.workspace.import.result.v1', ok: true,
+    message: `Imported Handoff package ${plan.packageId || ''}.`,
+    counts: { records: adapterResult.records?.length || 0, assets: adapterResult.assets?.length || 0, workspaceEntries: adapterResult.workspaceEntries?.length || 0, sourceReferences: plan.sourceReferences?.length || 0, warnings: plan.counts?.warnings || 0, errors: 0 },
+    diagnostics: { handoffPackage: true, packageId: plan.packageId || '', packageRepresentationSha256: plan.fileMap?.representationSha256 || '', sourceReferenceCount: plan.sourceReferences?.length || 0, noRemoteFetch: true, noSourceMutation: true },
+    at: typeof options.clock === 'function' ? options.clock() : new Date().toISOString()
+  });
+  next.activeWorkspaceId = workspaceId;
+  return {
+    ok: true,
+    state: next,
+    workspace,
+    workspaceId,
+    handoff,
+    adapterResult,
+    notice: `Imported Handoff package · ${adapterResult.records?.length || 0} local artifact${adapterResult.records?.length === 1 ? '' : 's'} · ${adapterResult.assets?.length || 0} asset${adapterResult.assets?.length === 1 ? '' : 's'} · ${plan.sourceReferences?.length || 0} source reference${plan.sourceReferences?.length === 1 ? '' : 's'}.`
+  };
+}
+
+
+function jsonSafePackageAsset(asset = {}) {
+  const bytes = asset?.bytes;
+  const byteArray = bytes instanceof Uint8Array
+    ? Array.from(bytes)
+    : ArrayBuffer.isView(bytes)
+      ? Array.from(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength))
+      : bytes instanceof ArrayBuffer
+        ? Array.from(new Uint8Array(bytes))
+        : Array.isArray(bytes) ? bytes.slice() : bytes;
+  return Object.assign({}, asset, byteArray === undefined ? {} : { bytes: byteArray });
+}
+
+function uniqueHandoffWorkspaceId(state = {}, preferred = '', packageId = '') {
+  const ids = new Set((Array.isArray(state?.workspaces) ? state.workspaces : []).map((workspace) => String(workspace?.id || '')).filter(Boolean));
+  const base = preferred || `handoff-${String(packageId || 'package').replace(/[^a-z0-9_-]+/gi, '-').slice(0, 36) || 'package'}`;
+  if (!ids.has(base)) return base;
+  const suffix = String(packageId || 'import').replace(/[^a-z0-9]+/gi, '').slice(-10) || 'import';
+  let candidate = `${base}--handoff-${suffix}`;
+  let serial = 2;
+  while (ids.has(candidate)) { candidate = `${base}--handoff-${suffix}-${serial}`; serial += 1; }
+  return candidate;
+}
+
+function compactSourceReference(reference = {}) {
+  return {
+    schema: String(reference.schema || 'tiinex.export.package.import.source-reference.v2'),
+    materialKind: String(reference.materialKind || ''), id: String(reference.id || ''), title: String(reference.title || ''), status: String(reference.status || ''), boundary: String(reference.boundary || ''),
+    target: structuredCloneSafe(reference.target || {}), packagePath: String(reference.packagePath || '')
+  };
+}
+
+function compactWorkspaceContext(context = {}) {
+  return {
+    schema: String(context.schema || ''), id: String(context.id || ''), title: String(context.title || context.name || ''), name: String(context.name || context.title || ''),
+    sourceOrder: Array.isArray(context.sourceOrder) ? context.sourceOrder.map(String) : [], materialMembership: structuredCloneSafe(context.materialMembership || {}), boundary: String(context.boundary || '')
+  };
+}
+
+function structuredCloneSafe(value) { return JSON.parse(JSON.stringify(value || {})); }
+function firstFinding(findings = []) { return String((findings || []).find((finding) => finding?.severity === 'error')?.message || (findings || [])[0]?.message || '').trim(); }

package/src/app/historyAuthority.js

@@ -0,0 +1,53 @@
+import { DurableLocalAuthority, TIINEX_HISTORY_AUTHORITY_KEY, TIINEX_HISTORY_AUTHORITY_SCHEMA } from './persistenceOwnership.js';
+
+export { TIINEX_HISTORY_AUTHORITY_KEY, TIINEX_HISTORY_AUTHORITY_SCHEMA };
+
+export function durableLocalAuthorityFromHistoryState(historyState = null) {
+  const metadata = historyState && typeof historyState === 'object' ? historyState[TIINEX_HISTORY_AUTHORITY_KEY] : null;
+  return metadata?.schema === TIINEX_HISTORY_AUTHORITY_SCHEMA && metadata?.durableLocalAuthority === DurableLocalAuthority.isolatedPreexistingRecovery
+    ? DurableLocalAuthority.isolatedPreexistingRecovery
+    : DurableLocalAuthority.normal;
+}
+
+export function durableLocalAuthorityForRoute(routeKind = '', historyState = null) {
+  if (String(routeKind || '') === 'public-target') return DurableLocalAuthority.isolatedPreexistingRecovery;
+  if (String(routeKind || '') === 'semantic-state') return durableLocalAuthorityFromHistoryState(historyState);
+  return DurableLocalAuthority.normal;
+}
+
+export function historyStatePatchForDurableLocalAuthority(authority = DurableLocalAuthority.normal) {
+  return {
+    [TIINEX_HISTORY_AUTHORITY_KEY]: authority === DurableLocalAuthority.isolatedPreexistingRecovery
+      ? Object.freeze({ schema: TIINEX_HISTORY_AUTHORITY_SCHEMA, durableLocalAuthority: DurableLocalAuthority.isolatedPreexistingRecovery })
+      : null
+  };
+}
+
+export function composeHistoryState(baseState = null, patch = {}) {
+  const out = baseState && typeof baseState === 'object' && !Array.isArray(baseState) ? Object.assign({}, baseState) : {};
+  for (const [key, value] of Object.entries(patch || {})) {
+    if (value == null) delete out[key];
+    else out[key] = value;
+  }
+  return out;
+}
+
+export function markCurrentHistoryDurableAuthority(historyLike = null, locationLike = null, authority = DurableLocalAuthority.normal) {
+  if (!historyLike?.replaceState) return null;
+  const nextState = composeHistoryState(historyLike.state, historyStatePatchForDurableLocalAuthority(authority));
+  const href = currentRelativeUrl(locationLike);
+  try {
+    historyLike.replaceState(nextState, '', href || undefined);
+    return nextState;
+  } catch (_) {
+    return null;
+  }
+}
+
+function currentRelativeUrl(locationLike = null) {
+  if (!locationLike) return '';
+  const pathname = String(locationLike.pathname || '');
+  const search = String(locationLike.search || '');
+  const hash = String(locationLike.hash || '');
+  return `${pathname}${search}${hash}`;
+}

package/src/app/initialWorkspaceBootstrapOperation.js

@@ -0,0 +1,105 @@
+import { prepareDefaultWorkspaceStartCommand } from './defaultWorkspaceStartCommand.js';
+import { prepareResolvedStartupWorkspaceCommand } from './startupWorkspaceCommand.js';
+import { resolveTiinexAppStartupGithubInput } from './tiinexAppStartupSource.js';
+import { applyMaterializedStartupWorkspaceConfig } from './startupWorkspaceConfigApplication.js';
+
+export async function runInitialWorkspaceBootstrapOperation({
+  runtimeApi = {},
+  state = {},
+  workspaceConfig = {},
+  storage = null,
+  locationLike = null,
+  windowObj = null,
+  fetchImpl = globalThis.fetch,
+  commit = null,
+  materializeSource = null,
+  setDiagnostics = null,
+  resolveStartupInput = resolveTiinexAppStartupGithubInput
+} = {}) {
+  if ((state.workspaces || []).length) return { ok: true, skipped: 'workspace-already-present', state };
+  const resolved = await resolveStartup(locationLike?.href || '', {
+    fetchImpl,
+    parseWorkspaceConfig: runtimeApi.config?.parseWorkspaceConfig,
+    locationLike,
+    windowObj,
+    hostWorkspace: windowObj?.TiinexWorkspace || windowObj?.tiinexWorkspace || windowObj?.TIINEX_WORKSPACE
+  }, resolveStartupInput);
+  const strongConfig = resolved?.ok && (resolved.startupClass === 'explicit-runtime-config' || resolved.startupClass === 'hosted-config');
+  if (strongConfig) return applyResolved({ runtimeApi, state, storage, resolved, commit, materializeSource, setDiagnostics, locationLike, workspaceConfig });
+  if (resolved?.ok && resolved.startupClass === 'packaged-fallback-config') {
+    return applyResolved({ runtimeApi, state, storage, resolved, commit, materializeSource, setDiagnostics, locationLike, workspaceConfig });
+  }
+  if (resolved?.explicitQueryRequested) return explicitStartupFailure({ resolved, state, setDiagnostics, locationLike });
+  return applyDefault({ runtimeApi, state, storage, workspaceConfig, commit, materializeSource, setDiagnostics });
+}
+
+async function resolveStartup(targetUrl, options, resolver = resolveTiinexAppStartupGithubInput) {
+  try {
+    return await resolver(targetUrl, options);
+  } catch (error) {
+    return { ok: false, message: error?.message || String(error || 'Startup config resolution failed.') };
+  }
+}
+
+async function applyResolved({ runtimeApi, state, storage, resolved, commit, materializeSource, setDiagnostics, locationLike, workspaceConfig }) {
+  const prepared = prepareResolvedStartupWorkspaceCommand({ lifecycle: runtimeApi.lifecycle, persistence: runtimeApi.persistence, state, resolved, storage });
+  if (!prepared?.ok) {
+    if (resolved?.explicitQueryRequested) return explicitStartupFailure({ resolved: Object.assign({}, resolved, { message: prepared?.message || resolved?.message || 'Explicit workspace startup failed.' }), state, setDiagnostics, locationLike });
+    return applyDefault({ runtimeApi, state, storage, workspaceConfig, commit, materializeSource, setDiagnostics });
+  }
+  setDiagnostics?.({
+    last: {
+      targetUrl: resolved.targetUrl || locationLike?.href || '',
+      ok: true,
+      selectedConvention: resolved.diagnostics?.selectedConvention || '',
+      selectedPlan: resolved.selectedPlan || '',
+      startupClass: resolved.startupClass || '',
+      input: resolved.input || null,
+      inputs: resolved.inputs || (resolved.input ? [resolved.input] : []),
+      diagnostics: resolved.diagnostics || null,
+      message: resolved.message || ''
+    }
+  });
+  const augmentedState = runtimeApi.persistence?.augmentStartupStateWithLocalRecovery?.(prepared.state, storage, { restoreFocus: !resolved?.explicitQueryRequested }) || prepared.state;
+  const workspace = (augmentedState.workspaces || []).find((item) => item.id === prepared.workspace?.id) || prepared.workspace;
+  let materialState = augmentedState;
+  for (const sourceInput of prepared.sourceInputs || (prepared.sourceInput ? [prepared.sourceInput] : [])) {
+    const loaded = await materializeSource?.(sourceInput, { state: materialState, workspaceId: sourceInput.workspaceId || workspace?.id, bufferProductState: true });
+    if (loaded?.state) materialState = loaded.state;
+  }
+  const appliedConfig = applyMaterializedStartupWorkspaceConfig({ runtimeApi, state: materialState, resolved, discoveryWorkspaceId: workspace?.id || prepared.workspace?.id || '' });
+  if (!appliedConfig?.ok) return { ok: false, error: appliedConfig?.error || 'startup.workspace-config-application-failed', message: appliedConfig?.message || 'Could not apply startup workspace config.', state: materialState, resolved };
+  if (appliedConfig.applied) {
+    materialState = appliedConfig.state;
+    for (const sourceInput of appliedConfig.sourceInputs || []) {
+      const loaded = await materializeSource?.(sourceInput, { state: materialState, workspaceId: sourceInput.workspaceId || appliedConfig.workspace?.id, bufferProductState: true });
+      if (loaded?.state) materialState = loaded.state;
+    }
+    commit?.(materialState, 'replace');
+    const appliedWorkspace = (materialState.workspaces || []).find((item) => item.id === appliedConfig.workspace?.id) || appliedConfig.workspace;
+    return { ok: true, selected: `${resolved.startupClass || 'resolved-config'}-workspace-artifact-applied`, state: materialState, workspace: appliedWorkspace, workspaces: appliedConfig.workspaces || [appliedWorkspace].filter(Boolean), startupRecord: appliedConfig.startupRecord };
+  }
+  commit?.(materialState, 'replace');
+  return { ok: true, selected: resolved.startupClass || 'resolved-config', state: materialState, workspace, workspaces: prepared.workspaces || [workspace].filter(Boolean) };
+}
+
+function explicitStartupFailure({ resolved = {}, state = {}, setDiagnostics = null, locationLike = null } = {}) {
+  const message = resolved?.message || resolved?.error || 'Explicit workspace startup failed.';
+  setDiagnostics?.({ last: { targetUrl: resolved.targetUrl || locationLike?.href || '', ok: false, startupClass: resolved.startupClass || 'explicit-workspace-failed', explicitQueryRequested: true, diagnostics: resolved.diagnostics || null, message } });
+  return { ok: false, error: 'startup.explicit-workspace-unavailable', message, explicitQueryRequested: true, state };
+}
+
+async function applyDefault({ runtimeApi, state, storage, workspaceConfig, commit, materializeSource, setDiagnostics }) {
+  const prepared = prepareDefaultWorkspaceStartCommand({ lifecycle: runtimeApi.lifecycle, persistence: runtimeApi.persistence, state, workspaceConfig, storage });
+  if (!prepared?.ok) return { ok: false, error: prepared?.error || 'startup.default-unavailable', message: prepared?.message || 'Default workspace config is unavailable.', state };
+  setDiagnostics?.({ last: prepared.diagnostics });
+  const augmentedState = runtimeApi.persistence?.augmentStartupStateWithLocalRecovery?.(prepared.state, storage) || prepared.state;
+  const workspace = (augmentedState.workspaces || []).find((item) => item.id === prepared.workspace?.id) || prepared.workspace;
+  let materialState = augmentedState;
+  for (const sourceInput of prepared.sourceInputs || (prepared.sourceInput ? [prepared.sourceInput] : [])) {
+    const loaded = await materializeSource?.(sourceInput, { state: materialState, workspaceId: sourceInput.workspaceId || workspace?.id, bufferProductState: true });
+    if (loaded?.state) materialState = loaded.state;
+  }
+  commit?.(materialState, 'replace');
+  return { ok: true, selected: 'embedded-default-workspace', state: materialState, workspace, workspaces: prepared.workspaces || [workspace].filter(Boolean) };
+}