@tiinex/app 0.1.1

package/src/app/workspaceGithubPublication.js

@@ -0,0 +1,237 @@
+import { buildPublicationPlan, buildPublicationResult } from '@tiinex/core/publication/publication.contract.js';
+import { buildPublicationPreflight } from '@tiinex/core/publication/publication.preflight.js';
+import { GITHUB_ISSUE_BODY_TARGET_KIND, GITHUB_ISSUE_COMMENT_TARGET_KIND } from '@tiinex/core/publication/publication.targetContract.js';
+import { normalizeGithubRepository, parseExactGithubIssueTarget, sameGithubRepository } from '@tiinex/core/sources/github/github.issueTarget.js';
+import { readExactGithubIssuePublicationRepresentation } from '../adapters/github/github.publicationRead.js';
+import { sha256Hex, utf8Bytes } from '@tiinex/core/export/package.bytes.js';
+
+export const GITHUB_PUBLICATION_MODE = Object.freeze({
+  createIssue: 'create-issue',
+  createComment: 'create-comment',
+  updateIssue: 'update-issue',
+  updateComment: 'update-comment'
+});
+
+export const GITHUB_PUBLICATION_HUMAN_MUTATION_ATTESTATION = 'human-github-web-mutation-confirmation';
+
+export function buildWorkspaceGithubPublicationPreflight(workspace = {}) { return buildPublicationPreflight(workspace); }
+
+export function buildWorkspaceGithubPublicationProduct(workspace = {}, input = {}, options = {}) {
+  const preflight = options.preflight || buildWorkspaceGithubPublicationPreflight(workspace);
+  const mode = normalizeMode(input.mode);
+  const modeSpec = modeSpecification(mode);
+  const recordId = String(input.recordId || '').trim();
+  const repository = String(input.repository || '');
+  const targetInput = String(input.targetInput || '');
+  const destination = {
+    provider: 'github',
+    repository,
+    targetKind: modeSpec.targetKind,
+    ...(modeSpec.targetField ? { [modeSpec.targetField]: targetInput } : {})
+  };
+  const plan = buildPublicationPlan(workspace, { recordId, destination, mutationPolicy: modeSpec.mutationPolicy, preflight });
+  const openUrl = publicationOpenUrl(plan);
+  const verificationTarget = String(input.finalTarget || (plan.mutationPolicy === 'update-known' ? plan.destination?.externalTarget || '' : ''));
+  const mutationTargetQualification = qualifyMutationTarget(plan, verificationTarget);
+  const latestReceipt = (Array.isArray(workspace.publicationReceipts) ? workspace.publicationReceipts : []).find((entry) => String(entry?.receipt?.localInputId || '') === recordId) || null;
+  return Object.freeze({
+    schema: 'tiinex.site.githubPublicationProduct.v1',
+    mode,
+    modes: publicationModes(),
+    eligibleRecords: preflight.publishableLocalDrafts || [],
+    preflight,
+    plan,
+    openUrl,
+    verificationTarget,
+    mutationTarget: mutationTargetQualification.target || null,
+    mutationTargetQualified: mutationTargetQualification.ok === true,
+    latestReceipt,
+    targetLabel: modeSpec.targetLabel,
+    targetRequired: Boolean(modeSpec.targetField),
+    targetPlaceholder: modeSpec.targetPlaceholder,
+    finalTargetRequired: plan.mutationPolicy !== 'update-known',
+    boundary: 'Guided browser routine only. Shared publication plan/result own payload and success; Site performs no GitHub mutation.'
+  });
+}
+
+export function publicationProgressFor(plan = {}, verificationTarget = '', progress = {}) {
+  const current = String(plan?.planSha256 || '');
+  const targetQualification = qualifyMutationTarget(plan, verificationTarget);
+  const mutationAttestation = targetQualification.ok ? qualifiedHumanMutationAttestation(current, targetQualification.target, progress.mutationAttestation) : null;
+  return Object.freeze({
+    ...progress,
+    mutationAttestation,
+    copied: Boolean(current && progress.copiedPlanSha256 === current),
+    opened: Boolean(current && progress.openedPlanSha256 === current),
+    attested: Boolean(mutationAttestation),
+    verified: Boolean(current && progress.verificationPlanSha256 === current && progress.result?.status === 'success' && targetQualification.ok && sameExactMutationTarget(targetQualification.target, progress.result?.remoteTarget))
+  });
+}
+
+export function confirmWorkspaceGithubPublicationMutation(plan = {}, options = {}) {
+  const planSha256 = String(plan?.planSha256 || '').trim();
+  if (plan.status !== 'ready' || !planSha256) return Object.freeze({ ok: false, error: 'publication.plan.not-ready', mutationAttestation: null, notice: 'Publication plan is not ready for human mutation confirmation.' });
+  const targetQualification = qualifyMutationTarget(plan, options.finalTarget);
+  if (!targetQualification.ok) return Object.freeze({ ok: false, error: targetQualification.error, mutationAttestation: null, notice: targetQualification.notice });
+  const mutationAttestation = Object.freeze({
+    schema: 'tiinex.site.githubPublicationHumanMutationAttestation.v2',
+    type: GITHUB_PUBLICATION_HUMAN_MUTATION_ATTESTATION,
+    planSha256,
+    mutationTarget: targetQualification.target,
+    confirmedAt: nowIso(options.clock),
+    boundary: 'Human confirms they performed the GitHub web mutation for this exact publication plan at this exact qualified GitHub target. Tiinex did not perform a hidden/API write.'
+  });
+  return Object.freeze({ ok: true, mutationAttestation, notice: 'Human GitHub mutation confirmed for this exact publication plan and exact target.' });
+}
+
+export async function copyWorkspaceGithubPublicationPayload(plan = {}, options = {}) {
+  if (plan.status !== 'ready') return Object.freeze({ ok: false, error: 'publication.plan.not-ready', planSha256: plan.planSha256 || '', notice: 'Publication plan is not ready.' });
+  const clipboard = options.clipboard;
+  if (!clipboard || typeof clipboard.writeText !== 'function') return Object.freeze({ ok: false, error: 'clipboard.unavailable', planSha256: plan.planSha256 || '', notice: 'Clipboard is unavailable.' });
+  try {
+    await clipboard.writeText(String(plan.outboundPayload?.content || ''));
+    return Object.freeze({ ok: true, planSha256: plan.planSha256 || '', payloadSha256: plan.outboundPayload?.sha256 || '', notice: 'Exact publication payload copied.' });
+  } catch (exception) {
+    return Object.freeze({ ok: false, error: 'clipboard.write-failed', exception, planSha256: plan.planSha256 || '', notice: 'Could not copy publication payload.' });
+  }
+}
+
+export function openWorkspaceGithubPublicationTarget(plan = {}, options = {}) {
+  if (plan.status !== 'ready') return Object.freeze({ ok: false, error: 'publication.plan.not-ready', planSha256: plan.planSha256 || '', notice: 'Publication plan is not ready.' });
+  const url = publicationOpenUrl(plan);
+  if (!url) return Object.freeze({ ok: false, error: 'publication.open-target.unavailable', planSha256: plan.planSha256 || '', notice: 'GitHub target is not qualified for opening.' });
+  const open = options.open || options.window?.open?.bind(options.window);
+  if (typeof open !== 'function') return Object.freeze({ ok: false, error: 'publication.open.unavailable', planSha256: plan.planSha256 || '', url, notice: 'Browser open is unavailable.' });
+  try {
+    const opened = open(url, '_blank', 'noopener,noreferrer');
+    if (opened === null || opened === false) return Object.freeze({ ok: false, error: 'publication.open.blocked', planSha256: plan.planSha256 || '', url, notice: 'GitHub window could not be opened.' });
+    return Object.freeze({ ok: true, planSha256: plan.planSha256 || '', url, notice: 'GitHub opened. This is not publication success.' });
+  } catch (exception) {
+    return Object.freeze({ ok: false, error: 'publication.open.failed', exception, planSha256: plan.planSha256 || '', url, notice: 'GitHub window could not be opened.' });
+  }
+}
+
+export async function verifyWorkspaceGithubPublication(plan = {}, input = {}) {
+  if (plan.status !== 'ready') return Object.freeze({ ok: false, error: 'publication.plan.not-ready', result: buildPublicationResult(plan, { state: 'failure', verificationStatus: 'not-run' }), notice: 'Publication plan is not ready.' });
+  const targetQualification = qualifyMutationTarget(plan, input.finalTarget);
+  if (!targetQualification.ok) {
+    const result = buildPublicationResult(plan, { state: 'failure', verificationStatus: 'failed', sourceTarget: { adapterId: 'github', targetKind: plan.destination?.targetKind || '', inputTarget: String(input.finalTarget || '') } });
+    return Object.freeze({ ok: false, error: targetQualification.error, result, executionAttestation: null, notice: targetQualification.notice });
+  }
+  const exactTarget = targetQualification.parsed;
+  const executionAttestation = qualifiedHumanMutationAttestation(String(plan.planSha256 || ''), targetQualification.target, input.mutationAttestation);
+  if (!executionAttestation) {
+    const result = buildPublicationResult(plan, { state: 'failure', verificationStatus: 'not-run', sourceTarget: { adapterId: 'github', targetKind: exactTarget.targetKind, inputTarget: exactTarget.inputTarget } });
+    return Object.freeze({
+      ok: false,
+      error: 'publication.verify.human-mutation-attestation-required',
+      result,
+      executionAttestation: null,
+      notice: 'Confirm that you posted or updated this exact payload at this exact GitHub target before verification. Copy/Open are not write evidence.'
+    });
+  }
+  try {
+    const observed = await readExactGithubIssuePublicationRepresentation(exactTarget, { fetchImpl: input.fetchImpl });
+    const verifiedPayloadSha256 = sha256Hex(utf8Bytes(String(observed.content || '')));
+    const result = buildPublicationResult(plan, {
+      state: 'success',
+      verificationStatus: 'verified',
+      verifiedPayloadSha256,
+      providerReceiptId: observed.providerReceiptId || '',
+      sourceTarget: { adapterId: 'github', targetKind: exactTarget.targetKind, inputTarget: exactTarget.inputTarget },
+      verification: { status: 'verified', method: observed.method || 'github-browser-issue-reader-exact-body', observedAt: observed.observedAt || nowIso(input.clock), note: 'Exact GitHub issue/comment body read after shared v446 target qualification.' }
+    });
+    return Object.freeze({ ok: result.status === 'success' && Boolean(result.sourceBinding), result, observed, executionAttestation, notice: result.status === 'success' ? 'Human-guided GitHub publication verified exactly.' : 'GitHub target was read, but exact publication verification failed.' });
+  } catch (exception) {
+    const result = buildPublicationResult(plan, { state: 'partial', verificationStatus: 'unavailable', sourceTarget: { adapterId: 'github', targetKind: exactTarget.targetKind, inputTarget: exactTarget.inputTarget }, verification: { status: 'unavailable', method: 'github-browser-issue-reader', observedAt: nowIso(input.clock), note: exception?.message || 'GitHub read unavailable.' } });
+    return Object.freeze({ ok: false, error: 'publication.verify.read-unavailable', exception, result, executionAttestation, notice: 'GitHub verification is unavailable; no source binding was created.' });
+  }
+}
+
+export function publicationOpenUrl(plan = {}) {
+  if (plan.status !== 'ready' || plan.destination?.provider !== 'github') return '';
+  const rawRepo = String(plan.destination?.repository || '').trim();
+  const repo = normalizeGithubRepository(rawRepo);
+  if (!repo) return '';
+  if (plan.mutationPolicy === 'create-new' && plan.destination?.targetKind === GITHUB_ISSUE_BODY_TARGET_KIND) return `https://github.com/${rawRepo}/issues/new`;
+  if (plan.mutationPolicy === 'create-comment' && plan.destination?.targetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND) {
+    const parsed = parseExactGithubIssueTarget(plan.destination?.containerTarget || '');
+    return parsed.ok ? parsed.issueTarget : '';
+  }
+  if (plan.mutationPolicy === 'update-known') {
+    const parsed = parseExactGithubIssueTarget(plan.destination?.externalTarget || '');
+    return parsed.ok ? parsed.inputTarget : '';
+  }
+  return '';
+}
+
+function publicationModes() {
+  return Object.freeze([
+    Object.freeze({ id: GITHUB_PUBLICATION_MODE.createIssue, label: 'Create new issue' }),
+    Object.freeze({ id: GITHUB_PUBLICATION_MODE.createComment, label: 'Create comment' }),
+    Object.freeze({ id: GITHUB_PUBLICATION_MODE.updateIssue, label: 'Update known issue' }),
+    Object.freeze({ id: GITHUB_PUBLICATION_MODE.updateComment, label: 'Update known comment' })
+  ]);
+}
+function normalizeMode(value = '') { return Object.values(GITHUB_PUBLICATION_MODE).includes(value) ? value : GITHUB_PUBLICATION_MODE.createIssue; }
+function modeSpecification(mode) {
+  if (mode === GITHUB_PUBLICATION_MODE.createComment) return { targetKind: GITHUB_ISSUE_COMMENT_TARGET_KIND, mutationPolicy: 'create-comment', targetField: 'containerTarget', targetLabel: 'Parent issue URL', targetPlaceholder: 'https://github.com/owner/repo/issues/123' };
+  if (mode === GITHUB_PUBLICATION_MODE.updateIssue) return { targetKind: GITHUB_ISSUE_BODY_TARGET_KIND, mutationPolicy: 'update-known', targetField: 'externalTarget', targetLabel: 'Exact issue URL', targetPlaceholder: 'https://github.com/owner/repo/issues/123' };
+  if (mode === GITHUB_PUBLICATION_MODE.updateComment) return { targetKind: GITHUB_ISSUE_COMMENT_TARGET_KIND, mutationPolicy: 'update-known', targetField: 'externalTarget', targetLabel: 'Exact comment permalink', targetPlaceholder: 'https://github.com/owner/repo/issues/123#issuecomment-456' };
+  return { targetKind: GITHUB_ISSUE_BODY_TARGET_KIND, mutationPolicy: 'create-new', targetField: '', targetLabel: 'Final issue URL after posting', targetPlaceholder: '' };
+}
+function qualifyMutationTarget(plan = {}, rawTarget = '') {
+  if (plan.status !== 'ready') return Object.freeze({ ok: false, error: 'publication.plan.not-ready', target: null, parsed: null, notice: 'Publication plan is not ready.' });
+  const knownTarget = plan.mutationPolicy === 'update-known' ? String(plan.destination?.externalTarget || '') : '';
+  const raw = String(rawTarget || knownTarget || '');
+  if (!raw) return Object.freeze({ ok: false, error: 'publication.attestation.target-required', target: null, parsed: null, notice: 'Supply the exact GitHub issue/comment target before confirming the human mutation.' });
+  const parsed = parseExactGithubIssueTarget(raw);
+  if (!parsed.ok) return Object.freeze({ ok: false, error: 'publication.attestation.target-invalid', target: null, parsed: null, notice: 'Mutation confirmation requires one exact supported GitHub issue/comment target.' });
+  if (parsed.targetKind !== String(plan.destination?.targetKind || '')) return Object.freeze({ ok: false, error: 'publication.attestation.target-kind-mismatch', target: null, parsed, notice: 'Mutation target kind differs from the publication plan.' });
+  if (!sameGithubRepository(parsed.repository, plan.destination?.repository || '')) return Object.freeze({ ok: false, error: 'publication.attestation.target-repo-mismatch', target: null, parsed, notice: 'Mutation target belongs to a different repository than the publication plan.' });
+  if (plan.mutationPolicy === 'create-comment') {
+    const container = parseExactGithubIssueTarget(plan.destination?.containerTarget || '');
+    if (!container.ok || parsed.issueTarget !== container.issueTarget) return Object.freeze({ ok: false, error: 'publication.attestation.target-container-mismatch', target: null, parsed, notice: 'Mutation comment target belongs to a different issue than the declared comment container.' });
+  }
+  if (plan.mutationPolicy === 'update-known') {
+    const expected = parseExactGithubIssueTarget(plan.destination?.externalTarget || '');
+    if (!expected.ok || parsed.inputTarget !== expected.inputTarget || parsed.targetKind !== expected.targetKind) return Object.freeze({ ok: false, error: 'publication.attestation.target-plan-mismatch', target: null, parsed, notice: 'Mutation confirmation must bind the exact known GitHub target already qualified by the publication plan.' });
+  }
+  const target = exactMutationTargetProjection(parsed);
+  return Object.freeze({ ok: true, target, parsed, error: '', notice: '' });
+}
+function exactMutationTargetProjection(parsed = {}) {
+  return Object.freeze({
+    provider: 'github',
+    targetKind: String(parsed.targetKind || ''),
+    inputTarget: String(parsed.inputTarget || ''),
+    repository: String(parsed.repository || ''),
+    issueNumberLexeme: String(parsed.issueNumber || ''),
+    commentId: String(parsed.commentId || ''),
+    issueTarget: String(parsed.issueTarget || '')
+  });
+}
+function sameExactMutationTarget(a = null, b = null) {
+  if (!a || !b) return false;
+  return String(a.targetKind || '') === String(b.targetKind || '') && String(a.inputTarget || '') === String(b.inputTarget || '');
+}
+function qualifiedHumanMutationAttestation(planSha256 = '', exactTarget = null, value = null) {
+  const current = String(planSha256 || '').trim();
+  if (!current || !exactTarget || !value || typeof value !== 'object') return null;
+  if (String(value.type || '') !== GITHUB_PUBLICATION_HUMAN_MUTATION_ATTESTATION) return null;
+  if (String(value.planSha256 || '') !== current) return null;
+  if (!sameExactMutationTarget(value.mutationTarget, exactTarget)) return null;
+  const parsed = parseExactGithubIssueTarget(value.mutationTarget?.inputTarget || '');
+  if (!parsed.ok || parsed.targetKind !== String(value.mutationTarget?.targetKind || '') || parsed.inputTarget !== String(value.mutationTarget?.inputTarget || '')) return null;
+  const confirmedAt = String(value.confirmedAt || '').trim();
+  if (!confirmedAt) return null;
+  return Object.freeze({
+    schema: 'tiinex.site.githubPublicationHumanMutationAttestation.v2',
+    type: GITHUB_PUBLICATION_HUMAN_MUTATION_ATTESTATION,
+    planSha256: current,
+    mutationTarget: exactMutationTargetProjection(parsed),
+    confirmedAt,
+    boundary: String(value.boundary || 'Human-confirmed GitHub web mutation for the exact plan at the exact qualified target; Tiinex did not perform a hidden/API write.')
+  });
+}
+function nowIso(clock) { return typeof clock === 'function' ? new Date(clock()).toISOString() : new Date().toISOString(); }

package/src/app/workspaceHandoffExport.js

@@ -0,0 +1,56 @@
+import { prepareWorkspaceHandoffExport } from '../export/handoff.plan.js';
+import { exportPackageZipBlob } from '@tiinex/core/export/package.zip.js';
+
+export function executeWorkspaceHandoffExportCommand(input = {}) {
+  const workspace = input.workspace;
+  if (!workspace) return { ok: false, error: 'workspace.missing', notice: 'No workspace to export.' };
+  const preparation = prepareWorkspaceHandoffExport(workspace, {
+    clock: input.clock,
+    includeDegraded: true
+  });
+  if (!preparation.executable) {
+    const reason = firstBlockingFinding(preparation.inspection?.findings || preparation.bundle?.findings || []);
+    return { ok: false, error: 'export.handoff.blocked', preparation, notice: reason ? `Handoff package blocked: ${reason}` : 'Handoff package is blocked by package inspection.' };
+  }
+  try {
+    const download = input.download || exportWorkspaceHandoffDownload;
+    const result = download(workspace, input.document || globalThis.document, input.window || globalThis.window || globalThis, preparation);
+    return {
+      ok: true,
+      preparation,
+      freshness: Object.freeze({ source: 'execution-workspace', workspaceId: String(workspace.id || ''), recordCount: Array.isArray(workspace.records) ? workspace.records.length : 0, assetCount: Array.isArray(workspace.assets) ? workspace.assets.length : 0 }),
+      bundle: preparation.bundle,
+      filename: result.filename,
+      notice: `Handoff package ${preparation.status}: ${preparation.bundle.counts.files} governed file${preparation.bundle.counts.files === 1 ? '' : 's'} · ${preparation.bundle.counts.localDraftFiles} local artifact${preparation.bundle.counts.localDraftFiles === 1 ? '' : 's'} · ${preparation.bundle.counts.sourceReferenceFiles + preparation.bundle.counts.assetReferenceFiles} source reference${preparation.bundle.counts.sourceReferenceFiles + preparation.bundle.counts.assetReferenceFiles === 1 ? '' : 's'}.`
+    };
+  } catch (error) {
+    return { ok: false, error: 'export.handoff.failed', exception: error, preparation, notice: 'Could not build or download Handoff package.' };
+  }
+}
+
+export function exportWorkspaceHandoffDownload(workspace = {}, doc = globalThis.document, win = globalThis.window || globalThis, preparation = null) {
+  const prepared = preparation || prepareWorkspaceHandoffExport(workspace);
+  if (!prepared.executable || prepared.inspection?.status !== 'valid') throw new Error('handoff-package-not-valid');
+  const blob = exportPackageZipBlob(prepared.bundle);
+  const url = win.URL.createObjectURL(blob);
+  const link = doc.createElement('a');
+  link.href = url;
+  link.download = handoffPackageFilename(workspace, prepared.bundle);
+  link.rel = 'noopener';
+  doc.body.appendChild(link);
+  link.click();
+  link.remove();
+  win.setTimeout(() => win.URL.revokeObjectURL(url), 1000);
+  return Object.freeze({ filename: link.download, bundle: prepared.bundle, inspection: prepared.inspection });
+}
+
+export function handoffPackageFilename(workspace = {}, bundle = {}) {
+  const slug = String(workspace.title || workspace.name || workspace.id || 'workspace').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48) || 'workspace';
+  const stamp = String(bundle.builtAt || new Date().toISOString()).replace(/[^0-9]/g, '').slice(0, 14) || 'session';
+  return `tiinex-handoff-${slug}-${stamp}.zip`;
+}
+
+function firstBlockingFinding(findings = []) {
+  const item = (Array.isArray(findings) ? findings : []).find((finding) => finding?.severity === 'error') || (Array.isArray(findings) ? findings : [])[0];
+  return String(item?.message || '').trim();
+}

package/src/app/workspaceHomeTarget.js

@@ -0,0 +1,9 @@
+export function workspaceHomeHref(workspaceConfig = {}, locationLike = null) {
+  const location = locationLike || globalThis.location || { href: '', pathname: '/', search: '' };
+  const identity = workspaceConfig?.viewerIdentity || {};
+  const configured = String(identity.workspaceHome || '').trim();
+  const publicViewer = String(identity.publicViewerUrl || '').trim();
+  return resolveHomeValue(configured, location) || resolveHomeValue(publicViewer, location) || cleanViewerHref(location);
+}
+function resolveHomeValue(value = '', location = {}) { const text = String(value || '').trim(); if (!text || /^(javascript|data|blob):/i.test(text)) return ''; if (text.startsWith('#')) return `${location.pathname || '/'}${location.search || ''}${text}`; try { return new URL(text, location.href || 'http://localhost/').href; } catch (_) { return ''; } }
+function cleanViewerHref(location = {}) { return `${location.pathname || '/'}${location.search || ''}`; }

package/src/app/workspaceMulticolumn.js

@@ -0,0 +1,113 @@
+import { hydrateUiWorkspace } from './recordUi.js';
+import { workspaceColumnCapacity, workspaceWindowFor } from './workspaceWindow.js';
+import { qualifiedSchemaFilterValue } from '../workspaces/workspace.displayFilters.js';
+import { normalizeTimePortalView } from '../workspaces/workspace.timePortal.js';
+import { resolveWorkspaceEntrypointViewIntent } from '../workspaces/workspace.entrypointViewIntent.js';
+
+const DEFAULT_WORKSPACE_VIEW = Object.freeze({ universe: 'column', workspaceVerse: 'feed', reader: 'scan', query: '', layoutMode: 'expanded' });
+
+export function defaultWorkspaceView() {
+  return Object.assign({}, DEFAULT_WORKSPACE_VIEW);
+}
+
+export function activeWorkspaceViewFor(state = {}, workspaceId = '') {
+  const id = String(workspaceId || '').trim();
+  const stored = id && state.workspaceViews && typeof state.workspaceViews === 'object' ? state.workspaceViews[id] : null;
+  if (stored && typeof stored === 'object') return normalizeWorkspaceView(stored);
+  if (id && id === state.activeWorkspaceId && state.view && typeof state.view === 'object') return normalizeWorkspaceView(state.view);
+  return defaultWorkspaceView();
+}
+
+export function workspaceLayoutModeFor(state = {}, workspaceId = '') {
+  return activeWorkspaceViewFor(state, workspaceId).layoutMode === 'compact' ? 'compact' : 'expanded';
+}
+
+export function stateForWorkspaceSurface(state = {}, workspaceId = '') {
+  return Object.assign({}, state, { view: activeWorkspaceViewFor(state, workspaceId) });
+}
+
+export function stateWithWorkspaceViewPatch(state = {}, workspaceId = '', patch = {}) {
+  const id = String(workspaceId || state.activeWorkspaceId || '').trim();
+  if (!id) return Object.assign({}, state, { view: normalizeWorkspaceView(Object.assign({}, state.view || {}, patch || {})) });
+  return stateWithWorkspaceView(state, id, normalizeWorkspaceView(Object.assign({}, activeWorkspaceViewFor(state, id), patch || {})));
+}
+
+export function stateWithWorkspaceViewUpdate(state = {}, workspaceId = '', updater = null) {
+  const id = String(workspaceId || state.activeWorkspaceId || '').trim();
+  const currentView = activeWorkspaceViewFor(state, id);
+  const nextView = typeof updater === 'function' ? updater(currentView) : currentView;
+  return stateWithWorkspaceView(state, id, normalizeWorkspaceView(nextView));
+}
+
+export function stateWithWorkspaceLayoutMode(state = {}, workspaceId = '', layoutMode = 'expanded') {
+  return stateWithWorkspaceViewPatch(state, workspaceId, { layoutMode: layoutMode === 'compact' ? 'compact' : 'expanded' });
+}
+
+export function stateWithActiveWorkspace(state = {}, workspaceId = '') {
+  const id = String(workspaceId || '').trim();
+  const workspaces = Array.isArray(state.workspaces) ? state.workspaces : [];
+  if (!id || !workspaces.some((workspace) => workspace.id === id)) return state;
+  const previousId = String(state.activeWorkspaceId || '').trim();
+  const views = Object.assign({}, state.workspaceViews || {});
+  if (previousId) views[previousId] = normalizeWorkspaceView(state.view || views[previousId] || DEFAULT_WORKSPACE_VIEW);
+  const nextView = normalizeWorkspaceView(views[id] || DEFAULT_WORKSPACE_VIEW);
+  views[id] = nextView;
+  return Object.assign({}, state, { activeWorkspaceId: id, view: nextView, workspaceViews: views });
+}
+
+export function stateWithWorkspacePresentationPruned(state = {}) {
+  const workspaces = Array.isArray(state.workspaces) ? state.workspaces : [];
+  const workspaceById = new Map(workspaces.map((workspace) => [String(workspace.id || ''), workspace]));
+  const allowed = new Set(workspaceById.keys());
+  const views = Object.fromEntries(Object.entries(state.workspaceViews || {})
+    .filter(([id]) => allowed.has(String(id)))
+    .map(([id, view]) => [id, normalizeWorkspaceViewForWorkspace(view, workspaceById.get(String(id)))]));
+  const activeId = allowed.has(String(state.activeWorkspaceId || '')) ? state.activeWorkspaceId : (workspaces[0]?.id || '');
+  const activeWorkspace = workspaceById.get(String(activeId || '')) || null;
+  const view = activeId
+    ? normalizeWorkspaceViewForWorkspace(views[activeId] || (activeId === state.activeWorkspaceId ? state.view : DEFAULT_WORKSPACE_VIEW), activeWorkspace)
+    : normalizeWorkspaceView(state.view || DEFAULT_WORKSPACE_VIEW);
+  if (activeId) views[activeId] = view;
+  return Object.assign({}, state, { activeWorkspaceId: activeId, view, workspaceViews: views });
+}
+
+export function visibleWorkspaceItemsFor(state = {}, { active = null, activeUi = null, viewportWidth = 0 } = {}) {
+  const windowState = workspaceWindowFor(state, { viewportWidth, activeWorkspaceId: active?.id || state.activeWorkspaceId });
+  return windowState.visible.map((workspace) => ({
+    workspace,
+    ui: workspace?.id === active?.id ? activeUi : hydrateUiWorkspace(workspace),
+    surfaceState: stateForWorkspaceSurface(state, workspace?.id),
+    layoutMode: workspaceLayoutModeFor(state, workspace?.id),
+    active: workspace?.id === active?.id
+  }));
+}
+
+export { workspaceColumnCapacity };
+
+function stateWithWorkspaceView(state = {}, workspaceId = '', view = {}) {
+  const id = String(workspaceId || '').trim();
+  const views = Object.assign({}, state.workspaceViews || {});
+  if (id) views[id] = normalizeWorkspaceView(view);
+  return Object.assign({}, state, {
+    view: id === state.activeWorkspaceId ? views[id] : normalizeWorkspaceView(state.view || DEFAULT_WORKSPACE_VIEW),
+    workspaceViews: views
+  });
+}
+
+function normalizeWorkspaceViewForWorkspace(view = {}, workspace = null) {
+  const next = resolveWorkspaceEntrypointViewIntent(normalizeWorkspaceView(view), workspace);
+  if (!next.displayOptions || typeof next.displayOptions !== 'object' || Array.isArray(next.displayOptions)) return next;
+  const schemaFilter = qualifiedSchemaFilterValue(next.displayOptions.schemaFilter, workspace?.records || []);
+  if (schemaFilter === next.displayOptions.schemaFilter) return next;
+  return Object.assign({}, next, { displayOptions: Object.assign({}, next.displayOptions, { schemaFilter }) });
+}
+
+function normalizeWorkspaceView(view = {}) {
+  const next = Object.assign({}, DEFAULT_WORKSPACE_VIEW, view || {});
+  if (!['feed', 'tree', 'graph', 'lineage', 'audit'].includes(String(next.workspaceVerse || ''))) next.workspaceVerse = 'feed';
+  next.layoutMode = next.layoutMode === 'compact' ? 'compact' : 'expanded';
+  const timePortal = normalizeTimePortalView(next.timePortal);
+  if (timePortal) next.timePortal = timePortal;
+  else delete next.timePortal;
+  return next;
+}

package/src/app/workspaceNavigationParity.case.mjs

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { buildWorkspaceDiscoveryView, buildDiscoveryMaterialIndex } from '../workspaces/workspace.discoveryView.js';
+import { buildWorkspaceLineageView } from '../workspaces/workspace.lineageView.js';
+import { buildWorkspacePathTree } from '../workspaces/workspace.pathTree.js';
+import { WORKSPACE_RECORD_PRIMARY_INTENT, workspaceRecordPrimaryIntent } from '../workspaces/workspace.navigation.js';
+import { stateWithRecordLineageFocused, stateWithWorkspaceViewPatchAndFocus, workspaceVerseNavigationPatch } from './workspaceScopedInteraction.js';
+
+const parent = record('parent', 'Root Parent', 'roots/parent.trace.md', '2026-09-01 09:00:00');
+const child = record('child', 'Focused Child', 'branches/deep/child.trace.md', '2026-09-02 09:00:00', '../../roots/parent.trace.md');
+const sibling = record('sibling', 'Sibling Note', 'branches/sibling.trace.md', '2026-09-01 12:00:00');
+const records = [parent, child, sibling];
+const workspace = { id: 'workspace-navigation', title: 'Navigation', records, assets: [] };
+const displayOptions = { leavesOnly: false, showSupportingMarkdown: true, showWorkspaceArtifacts: true, showAssets: false, schemaFilter: 'all', artifactFilter: 'all', sourceFilter: 'all' };
+
+// Feed and Tree are presentation projections over the same stable record identity.
+const feed = buildWorkspaceDiscoveryView(workspace, { records, displayOptions, query: '' });
+assert.strictEqual(feed.records.find((item) => item.id === child.id), child);
+const tree = buildWorkspacePathTree({ records: feed.records, assets: [] });
+const treeChild = findTreeRecord(tree, child.id);
+assert.ok(treeChild, 'Tree must contain the Feed-visible child');
+assert.strictEqual(treeChild.source, child, 'Tree must preserve the exact loaded record identity used by Feed');
+assert.equal(treeChild.path, 'branches/deep/child.trace.md');
+assert.equal(workspaceRecordPrimaryIntent({ surface: 'feed' }), WORKSPACE_RECORD_PRIMARY_INTENT.open);
+assert.equal(workspaceRecordPrimaryIntent({ surface: 'tree' }), WORKSPACE_RECORD_PRIMARY_INTENT.open);
+assert.equal(workspaceRecordPrimaryIntent({ surface: 'lineage' }), WORKSPACE_RECORD_PRIMARY_INTENT.toggleLineagePreview);
+assert.equal(workspaceRecordPrimaryIntent({ surface: 'tree', selectionActive: true, selectionCandidate: { id: child.id } }), WORKSPACE_RECORD_PRIMARY_INTENT.select);
+assert.equal(workspaceRecordPrimaryIntent({ surface: 'tree', selectionActive: true }), WORKSPACE_RECORD_PRIMARY_INTENT.unavailable);
+
+// Path Tree truth remains independent from declared Parent truth.
+const lineage = buildWorkspaceLineageView(workspace, { records, selectedRecordId: child.id });
+assert.ok(lineage.edges.some((edge) => edge.kind === 'parent' && edge.from === parent.id && edge.to === child.id), 'Lineage must follow the declared Parent Trace across unrelated path folders');
+assert.deepEqual(lineage.selectedTraversal.nodes.map((node) => node.id), [child.id, parent.id]);
+assert.equal(findTreeRecord(tree, parent.id).path, 'roots/parent.trace.md');
+assert.equal(findTreeRecord(tree, child.id).path, 'branches/deep/child.trace.md');
+
+// Search/filtering and optional material-index reuse are presentation-only and semantically equivalent.
+const filterOptions = { ...displayOptions, schemaFilter: 'tiinex.topic.v1' };
+const uncached = buildWorkspaceDiscoveryView(workspace, { records, displayOptions: filterOptions, query: 'focused' });
+const cached = buildWorkspaceDiscoveryView(workspace, { records, displayOptions: filterOptions, query: 'focused', materialIndex: buildDiscoveryMaterialIndex(records) });
+assert.deepEqual(cached.records.map((item) => item.id), uncached.records.map((item) => item.id));
+assert.deepEqual(cached.records.map((item) => item.id), [child.id]);
+const lineageAfterFiltering = buildWorkspaceLineageView(workspace, { records, selectedRecordId: child.id });
+assert.deepEqual(lineageAfterFiltering.edges, lineage.edges, 'Discovery filtering must not mutate declared lineage truth');
+
+// Feed ordering is deterministic and independent of loaded array order.
+const orderA = buildWorkspaceDiscoveryView(workspace, { records: [parent, child, sibling], displayOptions, query: '' }).records.map((item) => item.id);
+const orderB = buildWorkspaceDiscoveryView(workspace, { records: [sibling, parent, child], displayOptions, query: '' }).records.map((item) => item.id);
+assert.deepEqual(orderA, orderB);
+assert.deepEqual(orderA, [child.id, sibling.id, parent.id]);
+
+// Artifact -> Lineage -> Back preserves discovery context while clearing lineage-only state.
+const discoveryView = {
+  universe: 'column',
+  workspaceVerse: 'tree',
+  query: 'focused',
+  displayOptions: { ...displayOptions, mismatchesOnly: true },
+  expandedTreeFolders: ['branches', 'branches/deep'],
+  scrollPositions: { 'workspace-navigation:tree:focused::display': 318 }
+};
+const state = { activeWorkspaceId: workspace.id, workspaces: [workspace], view: discoveryView, workspaceViews: { [workspace.id]: discoveryView } };
+const lineageState = stateWithRecordLineageFocused(state, workspace.id, child.id, 1280);
+assert.equal(lineageState.view.workspaceVerse, 'lineage');
+assert.equal(lineageState.view.lineageReturnVerse, 'tree');
+assert.equal(lineageState.view.selectedRecordId, child.id);
+assert.equal(lineageState.view.query, discoveryView.query);
+assert.deepEqual(lineageState.view.displayOptions, discoveryView.displayOptions);
+assert.deepEqual(lineageState.view.expandedTreeFolders, discoveryView.expandedTreeFolders);
+assert.deepEqual(lineageState.view.scrollPositions, discoveryView.scrollPositions);
+const returned = stateWithWorkspaceViewPatchAndFocus(lineageState, workspace.id, workspaceVerseNavigationPatch(lineageState.view.lineageReturnVerse), 1280);
+assert.equal(returned.view.workspaceVerse, 'tree');
+assert.equal(returned.view.selectedRecordId, '');
+assert.equal(returned.view.lineageReturnVerse, '');
+assert.equal(returned.view.query, discoveryView.query);
+assert.deepEqual(returned.view.displayOptions, discoveryView.displayOptions);
+assert.deepEqual(returned.view.expandedTreeFolders, discoveryView.expandedTreeFolders);
+assert.deepEqual(returned.view.scrollPositions, discoveryView.scrollPositions);
+
+// UI wiring must expose opening and lineage as distinct actions rather than conflating primary click with lineage.
+const cardSource = fs.readFileSync(new URL('../schemas/workspace/workspace.cards.views.jsx', import.meta.url), 'utf8');
+const treeSource = fs.readFileSync(new URL('../schemas/workspace/workspace.tree.views.jsx', import.meta.url), 'utf8');
+const detailSource = fs.readFileSync(new URL('../schemas/workspace/workspace.recordDialogs.views.jsx', import.meta.url), 'utf8');
+assert.ok(cardSource.includes("label: lineageContext ? 'Anchor' : 'Lineage'"));
+assert.ok(cardSource.includes('return onOpenRecord?.(record.id);'));
+assert.ok(treeSource.includes('return onOpenRecord?.(item.source.id);'));
+assert.ok(treeSource.includes('Open lineage for ${item.name || item.title || \'artifact\'}'));
+assert.ok(detailSource.includes('onLineage && !historical'));
+assert.ok(detailSource.includes('>Lineage</Button>'));
+
+console.log('✓ Viewer navigation parity invariants passed');
+
+function record(id, title, path, createdAt, trace = '') {
+  const parentBlock = trace ? `- Parent\n  - Parent Schema: [tiinex.topic.v1](tiinex.topic.v1.schema.md)\n  - Trace: [Parent](${trace})\n` : '';
+  const markdown = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](tiinex.root.v1.schema.md)\n${parentBlock}- Current\n  - Current Schema: [tiinex.topic.v1](tiinex.topic.v1.schema.md)\n  - Created At: ${createdAt}\n  - Summary: ${title}\n\n---\n\n# ${title}\n\n${title} body.\n\n---\n\n# Continuity Integrity\n\n- local-test\n  - Towards: self\n  - Value: ${id}-self\n`;
+  return Object.assign(createRecordFromMarkdown(markdown, { path, sourceMode: 'local-test' }), { id });
+}
+
+function findTreeRecord(tree, id) {
+  const visit = (folder) => {
+    const direct = (folder.items || []).find((item) => item.type === 'record' && item.source?.id === id);
+    if (direct) return direct;
+    for (const childFolder of folder.folders || []) {
+      const found = visit(childFolder);
+      if (found) return found;
+    }
+    return null;
+  };
+  return visit({ folders: tree.folders || [], items: tree.items || [] });
+}

package/src/app/workspaceOpenProgress.js

@@ -0,0 +1,26 @@
+import { setWorkspaceDiscoveryProgress } from '../workspaces/workspace.discoveryProgress.js';
+
+export function stateWithWorkspaceRecordOpenProgress(openedState = {}, workspaceId = '', sourceInputs = [], entry = {}) {
+  const inputs = Array.isArray(sourceInputs) ? sourceInputs : [];
+  if (!inputs.length) return openedState;
+  let next = openedState;
+  for (const input of inputs) {
+    const targetWorkspaceId = input.workspaceId || workspaceId || '';
+    if (!targetWorkspaceId) continue;
+    const primary = input || {};
+    const sourceId = String(primary.sourceId || primary.id || '').trim();
+    const sourceLabel = String(primary.label || primary.repository || entry?.title || 'Workspace source').trim();
+    const workspace = (Array.isArray(next?.workspaces) ? next.workspaces : []).find((item) => item.id === targetWorkspaceId);
+    const resolvedSourceId = sourceId || (Array.isArray(workspace?.sources) ? workspace.sources.find((source) => String(source.label || '') === sourceLabel || String(source.repo || source.repository || '') === String(primary.repository || ''))?.id : '') || '';
+    const progress = setWorkspaceDiscoveryProgress(next, targetWorkspaceId, {
+      sourceId: resolvedSourceId,
+      phase: 'workspace-open-source-queued',
+      label: `${sourceLabel} source loading queued`,
+      active: true,
+      quantified: false,
+      discoveryState: 'loading'
+    });
+    if (progress?.ok) next = progress.state;
+  }
+  return next;
+}

package/src/app/workspacePlacementOptions.js

@@ -0,0 +1,46 @@
+export const WORKSPACE_PLACEMENT_OPTIONS_SCHEMA_ID = 'tiinex.site.workspace-placement-options.v1';
+
+export function workspacePlacementOptions(state = {}, workspaceId = '') {
+  const id = token(workspaceId);
+  const workspaces = Array.isArray(state?.workspaces) ? state.workspaces : [];
+  const target = workspaces.find((workspace) => token(workspace?.id) === id);
+  if (!target) return Object.freeze({ schema: WORKSPACE_PLACEMENT_OPTIONS_SCHEMA_ID, state: 'workspace-unavailable', options: Object.freeze([]) });
+  const options = [];
+  for (const workspace of workspaces) {
+    const currentId = token(workspace?.id);
+    for (const path of folderPathsForWorkspace(workspace)) {
+      const sameWorkspace = currentId === id;
+      options.push(Object.freeze({
+        kind: 'folder', key: placementFolderSelectionKey(currentId, path), workspaceId: currentId, path,
+        title: path === '.' ? `${workspace.name || workspace.title || currentId} root` : path,
+        enabled: sameWorkspace,
+        reason: sameWorkspace ? '' : 'cross-workspace-placement-authority-unavailable',
+        boundary: sameWorkspace ? 'Same-workspace storage coordinate only; does not change Parent, Reference, or provenance.' : 'Cross-workspace placement requires semantic/lifecycle authority not present in the current canonical create command.'
+      }));
+    }
+  }
+  return Object.freeze({ schema: WORKSPACE_PLACEMENT_OPTIONS_SCHEMA_ID, state: 'qualified', workspaceId: id, options: Object.freeze(options), qualifiedOptions: Object.freeze(options.filter((item) => item.enabled)), unavailableOptions: Object.freeze(options.filter((item) => !item.enabled)), crossWorkspaceClassification: 'PLACEMENT AUTHORITY ESCALATION REQUIRED' });
+}
+
+export function folderPathsForWorkspace(workspace = {}) {
+  const folders = new Set(['.topics']);
+  for (const record of Array.isArray(workspace.records) ? workspace.records : []) {
+    const path = canonicalPath(record?.path || '');
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length <= 1) continue;
+    let current = '';
+    for (const part of parts.slice(0, -1)) { current = current ? `${current}/${part}` : part; folders.add(current); }
+  }
+  return Object.freeze([...folders].sort((a,b) => a.localeCompare(b)));
+}
+
+export function explicitPlacementPath(defaultPath = '', folder = '') {
+  const path = canonicalPath(defaultPath), dir = canonicalFolder(folder);
+  const name = path.split('/').filter(Boolean).at(-1) || '';
+  if (!name || !dir) return '';
+  return dir === '.' ? name : `${dir}/${name}`;
+}
+export function placementFolderSelectionKey(workspaceId = '', path = '') { return `placement-folder:${token(workspaceId)}:${canonicalFolder(path)}`; }
+function canonicalPath(value = '') { return token(value).replace(/\\/g,'/').replace(/^\/+|\/+$/g,'').replace(/\/+/g,'/'); }
+function canonicalFolder(value = '') { const v=canonicalPath(value); return v || '.'; }
+function token(value = '') { return String(value || '').trim(); }