mcard-studio 0.0.0-stage → 0.0.1

package/src/services/markdownLinkFacetDispatcher.ts

@@ -0,0 +1,104 @@
+/**
+ * Markdown Link Facet Dispatcher & Unified Protocol Guard
+ * Canonical Path: src/services/markdownLinkFacetDispatcher.ts
+ * Deliverable: DEL-198-04
+ *
+ * Extends Sprint 195's markdownService.ts:
+ *   - Strictly enforces single protocol: 'mcard://' (standalone pcard:// and vcard:// prohibited)
+ *   - Dispatches ?facet=pcard&action=run to stage and execute PCard processes in CLM Viewlet
+ *   - Dispatches ?facet=vcard to inspect VCard execution traces in TraceInspector
+ */
+
+import { resolveMCardUri, handleMCardLinkClick } from './markdownService';
+import { openMCardFile, $mcardTree, type PCardNode } from '../stores/mcardStore';
+import { PCardDispatcher } from './pcardDispatcher';
+import { VCardTraceRecorder } from '../fiber/vcardTrace';
+
+export interface FacetDispatchResult {
+  handled: boolean;
+  facet?: string;
+  action?: string;
+  targetHandle: string;
+  pcardExecutionResult?: any;
+  trace?: any;
+}
+
+export class MarkdownLinkFacetDispatcher {
+  /**
+   * Resolves and dispatches any mcard:// link with facet parameters.
+   * Throws MISU error if any prohibited standalone protocol (pcard:// or vcard://) is supplied.
+   */
+  static async dispatchLink(uri: string): Promise<FacetDispatchResult> {
+    // Protocol validation guard
+    if (uri.startsWith('pcard://') || uri.startsWith('vcard://')) {
+      const scheme = uri.split('://')[0];
+      throw new Error(`[MISU] Prohibited protocol '${scheme}:'. Only 'mcard://' is permitted.`);
+    }
+
+    if (!uri.startsWith('mcard://')) {
+      throw new Error(`[MISU] Prohibited protocol. Only 'mcard://' is permitted.`);
+    }
+
+    const resolved = resolveMCardUri(uri);
+    if (!resolved) {
+      return { handled: false, targetHandle: '' };
+    }
+
+    const { handleOrHash, facet, action } = resolved;
+    const tree = $mcardTree.get();
+
+    // 1. Facet: pcard with action: run
+    if (facet === 'pcard' && action === 'run') {
+      const pcardNode: PCardNode = {
+        handle: handleOrHash,
+        hash: `hash:${handleOrHash}`,
+        path: `computable_knowledge/Concrete/${handleOrHash}`,
+        name: handleOrHash,
+        mimeType: 'text/typescript',
+        detectedType: 'pcard',
+        subclass: 'PCard',
+        epistemicStatus: 'theorem',
+        readOnly: false,
+        polynomialDegree: 1,
+        coeffects: ['config.kernel', 'identity.did'],
+        handlerUri: `mcard://${handleOrHash}`,
+        executionMode: 'client-wasm',
+        prescribedTransitions: [{ id: 't0', name: 'fire', targetInvariant: 'NoetherianConservation' }],
+      };
+
+      openMCardFile(pcardNode);
+      const executionResult = await PCardDispatcher.dispatchPCard(pcardNode);
+
+      return {
+        handled: true,
+        facet: 'pcard',
+        action: 'run',
+        targetHandle: handleOrHash,
+        pcardExecutionResult: executionResult,
+      };
+    }
+
+    // 2. Facet: vcard (Inspect Trace)
+    if (facet === 'vcard') {
+      const trace = VCardTraceRecorder.getTrace(handleOrHash) || VCardTraceRecorder.getRecentTraces()[0];
+      return {
+        handled: true,
+        facet: 'vcard',
+        targetHandle: handleOrHash,
+        trace,
+      };
+    }
+
+    // 3. Standard MCard Navigation
+    const navigated = handleMCardLinkClick(uri);
+    return {
+      handled: navigated,
+      facet,
+      action,
+      targetHandle: handleOrHash,
+    };
+  }
+}
+
+export const dispatchMarkdownFacetUri = MarkdownLinkFacetDispatcher.dispatchLink;
+export default MarkdownLinkFacetDispatcher;

package/src/services/markdownService.ts

@@ -0,0 +1,156 @@
+/**
+ * Built-in Markdown Service & mcard:// Hyperlink Resolver
+ * Canonical Path: src/services/markdownService.ts
+ *
+ * Enforces single protocol 'mcard://'. Rewrites hyperlinks to dispatch
+ * MCard CAS retrieval in Card Panel.
+ */
+
+import { openMCardFile, $mcardTree } from '../stores/mcardStore';
+import { findMCardByTarget } from './mcardVfs';
+
+export function resolveMCardUri(uri: string): { handleOrHash: string; facet?: string; action?: string; heading?: string } | null {
+  if (!uri.startsWith('mcard://')) {
+    return null;
+  }
+
+  const raw = uri.replace('mcard://', '');
+  const [targetAndAnchor, queryString] = raw.split('?');
+  const [target, heading] = targetAndAnchor.split('#');
+  const params = new URLSearchParams(queryString || '');
+
+  return {
+    handleOrHash: target,
+    heading: heading ? decodeURIComponent(heading) : undefined,
+    facet: params.get('facet') || undefined,
+    action: params.get('action') || undefined,
+  };
+}
+
+export function handleMCardLinkClick(targetOrUri: string): boolean {
+  if (!targetOrUri) return false;
+
+  let lookup = targetOrUri;
+  if (lookup.startsWith('mcard://')) {
+    const resolved = resolveMCardUri(lookup);
+    if (resolved) {
+      lookup = resolved.handleOrHash;
+    }
+  }
+
+  // Strip query and anchor
+  lookup = lookup.split('?')[0].split('#')[0];
+
+  const tree = $mcardTree.get();
+  // 1. Resolve via findMCardByTarget
+  const found = findMCardByTarget(lookup, null, tree);
+
+  if (found) {
+    openMCardFile(found);
+    return true;
+  }
+
+  console.warn(`[MarkdownService] MCard target not found in VFS: ${targetOrUri}`);
+  return false;
+}
+
+// Bind to window for global inline hyperlink dispatch
+if (typeof window !== 'undefined') {
+  (window as any).__CLM_NAVIGATE_MCARD__ = handleMCardLinkClick;
+}
+
+/**
+ * Basic lightweight Markdown renderer that resolves mcard:// and Obsidian links
+ */
+export function renderMarkdownToHtml(markdown: string): string {
+  if (!markdown) return '';
+
+  let html = markdown
+    // Escape basic HTML
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    // Headings
+    .replace(/^### (.*$)/gim, '<h3>$1</h3>')
+    .replace(/^## (.*$)/gim, '<h2>$1</h2>')
+    .replace(/^# (.*$)/gim, '<h1>$1</h1>')
+    // Bold & Italic
+    .replace(/\*\*(.*?)\*\*/gim, '<strong>$1</strong>')
+    .replace(/\*(.*?)\*/gim, '<em>$1</em>')
+    // Obsidian Highlights ==text==
+    .replace(/==(.*?)==/gim, '<mark class="obsidian-highlight" style="background: rgba(255, 215, 0, 0.25); color: #ffe066; padding: 1px 4px; border-radius: 2px;">$1</mark>')
+    // Obsidian Strikethrough ~~text~~
+    .replace(/~~(.*?)~~/gim, '<del style="opacity: 0.6;">$1</del>')
+    // Code blocks
+    .replace(/```([\s\S]*?)```/gim, '<pre><code>$1</code></pre>')
+    .replace(/`([^`]+)`/gim, '<code>$1</code>')
+    // Obsidian Wikilinks [[target|alias]] or [[target]]
+    .replace(/\[\[([^\]\|#]+)(?:#([^\]\|]+))?(?:\|([^\]]+))?\]\]/g, (_match, target, heading, alias) => {
+      const cleanTarget = (target || '').trim();
+      const cleanHeading = (heading || '').trim();
+      const label = (alias || cleanTarget || cleanHeading).trim();
+      const uri = `mcard://${cleanTarget}${cleanHeading ? '#' + encodeURIComponent(cleanHeading) : ''}`;
+      return `<a href="${uri}" class="obsidian-wikilink mcard-hyperlink" data-mcard-target="${cleanTarget}" ${cleanHeading ? `data-mcard-heading="${cleanHeading}"` : ''} onclick="window.__CLM_NAVIGATE_MCARD__ && window.__CLM_NAVIGATE_MCARD__('${cleanTarget}'); return false;" style="color: #75beff; text-decoration: none; border-bottom: 1px dashed rgba(117, 190, 255, 0.6); padding: 0 2px;"><span style="opacity: 0.7; margin-right: 3px;">📄</span>${label}</a>`;
+    })
+    // mcard:// links
+    .replace(
+      /\[(.*?)\]\((mcard:\/\/[^\)]+)\)/gim,
+      '<a href="$2" class="mcard-hyperlink" data-mcard-uri="$2" onclick="window.__CLM_NAVIGATE_MCARD__ && window.__CLM_NAVIGATE_MCARD__(\'$2\'); return false;">$1</a>'
+    )
+    // Regular links
+    .replace(/\[(.*?)\]\((.*?)\)/gim, '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>')
+    // Horizontal rules (dividing line: ---, ***, ___)
+    .replace(/^[ \t]*(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})[ \t]*$/gm, '<hr class="obsidian-divider" style="border: none; border-top: 1px solid var(--vscode-editorGroup-border, rgba(255, 255, 255, 0.15)); margin: 24px 0; width: 100%; box-sizing: border-box;" />');
+
+  // GFM Tables
+  const tableBlockRegex = /((?:^[ \t]*\|.+?\|[ \t]*\r?\n)(?:^[ \t]*\|(?:\s*:?-+:?\s*\|)+\s*\r?\n)(?:^[ \t]*\|.+?\|[ \t]*(?:\r?\n|$))+)/gm;
+  html = html.replace(tableBlockRegex, (match) => {
+    const lines = match.trim().split(/\r?\n/);
+    if (lines.length < 2) return match;
+
+    const parseCells = (line: string) => {
+      let t = line.trim();
+      if (t.startsWith('|')) t = t.slice(1);
+      if (t.endsWith('|')) t = t.slice(0, -1);
+      return t.split('|').map((c) => c.trim());
+    };
+
+    const headerCells = parseCells(lines[0]);
+    const delimCells = parseCells(lines[1]);
+    const isValidDelim = delimCells.length > 0 && delimCells.every((c) => /^:?-+:?$/.test(c));
+    if (!isValidDelim) return match;
+
+    const alignments = delimCells.map((c) => {
+      const left = c.startsWith(':');
+      const right = c.endsWith(':');
+      if (left && right) return 'center';
+      if (right) return 'right';
+      return 'left';
+    });
+
+    let tbl = '<div class="markdown-table-wrapper" style="margin: 16px 0; overflow-x: auto;"><table class="markdown-table" style="width: 100%; border-collapse: collapse; font-size: 12.5px; text-align: left;"><thead><tr>';
+    headerCells.forEach((h, idx) => {
+      tbl += `<th style="padding: 8px 12px; border: 1px solid var(--vscode-editorGroup-border, #3c3c3c); font-weight: 600; text-align: ${alignments[idx] || 'left'};">${h}</th>`;
+    });
+    tbl += '</tr></thead><tbody>';
+
+    for (let i = 2; i < lines.length; i++) {
+      const rowLine = lines[i].trim();
+      if (!rowLine) continue;
+      const rowCells = parseCells(rowLine);
+      tbl += '<tr>';
+      headerCells.forEach((_, idx) => {
+        tbl += `<td style="padding: 8px 12px; border: 1px solid var(--vscode-editorGroup-border, #3c3c3c); text-align: ${alignments[idx] || 'left'};">${rowCells[idx] || ''}</td>`;
+      });
+      tbl += '</tr>';
+    }
+    tbl += '</tbody></table></div>';
+    return tbl;
+  });
+
+  // Paragraph breaks
+  html = html.replace(/\n\n+/gim, '<br/><br/>');
+  html = html.replace(/(?:<br\/>\s*)+(<hr[^>]*>)(?:\s*<br\/>)+/gi, '$1');
+
+  return html;
+}

package/src/services/mcardExecutionService.ts

@@ -0,0 +1,139 @@
+/**
+ * MCard Execution Telemetry & CAS Sealing Service
+ * Canonical Path: src/services/mcardExecutionService.ts
+ * Deliverables: DEL-267-02, DEL-265-05
+ *
+ * Implements the "Everything is an MCard" execution paradigm:
+ * Every execution (convergent witness, assertion failure, or runtime exception)
+ * is instantiated and sealed as an immutable, content-addressed MCard in CAS.
+ */
+
+import { MCard, AgentDid } from 'clm-kernel';
+import { studioMCardFs } from './mcardVfs';
+import type { CLMTestCase } from './clmParserService';
+import type { VCardExecutionTrace } from '../fiber/vcardTrace';
+
+export type ExecutionOutcomeStatus = 'success' | 'failure' | 'exception';
+
+export interface StageTimings {
+  prepMs: number;
+  execMs: number;
+  postMs: number;
+  totalMs: number;
+}
+
+export interface ExecutionOutcomePayload {
+  readonly status: ExecutionOutcomeStatus;
+  readonly testCaseId: string;
+  readonly testCaseTitle: string;
+  readonly pcardHandle: string;
+  readonly inputContext: Record<string, unknown>;
+  readonly stageTimings: StageTimings;
+  readonly timestamp: string;
+  // For success:
+  readonly result?: unknown;
+  readonly vcardHash?: string;
+  // For failure:
+  readonly expected?: unknown;
+  readonly actual?: unknown;
+  readonly diff?: string;
+  // For exception:
+  readonly errorType?: string;
+  readonly errorMessage?: string;
+  readonly errorStack?: string;
+  readonly trace?: VCardExecutionTrace;
+}
+
+export interface SealedExecutionRecord {
+  id: string;
+  uri: string;
+  mcard: MCard;
+  status: ExecutionOutcomeStatus;
+  testCaseTitle: string;
+  stageTimings: StageTimings;
+  timestamp: string;
+  vcardHash?: string;
+  payload: ExecutionOutcomePayload;
+}
+
+/**
+ * Synthesizes, seals, and commits an Execution Outcome MCard into studioMCardFs.
+ */
+export async function sealExecutionOutcome(params: {
+  pcardHandle: string;
+  testCase: CLMTestCase;
+  testCaseIndex: number;
+  status: ExecutionOutcomeStatus;
+  stageTimings: StageTimings;
+  input: Record<string, unknown>;
+  result?: unknown;
+  expected?: unknown;
+  diff?: string;
+  vcardHash?: string;
+  error?: Error;
+  trace?: VCardExecutionTrace;
+}): Promise<SealedExecutionRecord> {
+  const timestamp = new Date().toISOString();
+  const testId = params.testCase.id || `tc-${params.testCaseIndex}`;
+  const testTitle = params.testCase.given || params.testCase.description || params.testCase.name || testId;
+
+  const payload: ExecutionOutcomePayload = {
+    status: params.status,
+    testCaseId: testId,
+    testCaseTitle: testTitle,
+    pcardHandle: params.pcardHandle,
+    inputContext: params.input,
+    stageTimings: params.stageTimings,
+    timestamp,
+    result: params.result,
+    vcardHash: params.vcardHash,
+    expected: params.expected,
+    actual: params.result,
+    diff: params.diff,
+    errorType: params.error?.name,
+    errorMessage: params.error?.message,
+    errorStack: params.error?.stack,
+    trace: params.trace,
+  };
+
+  const uri = `mcard:eventlog/${params.pcardHandle.replace(/[^a-zA-Z0-9_-]/g, '_')}/${testId}/${Date.now()}`;
+  const authorDid = AgentDid.create('did:clm:agent:fiber_runtime');
+  const metadata = new Map<string, unknown>([
+    ['execution/status', params.status],
+    ['execution/pcard', params.pcardHandle],
+    ['execution/test_case', testTitle],
+    ['execution/duration_ms', params.stageTimings.totalMs],
+    ['execution/vcard_hash', params.vcardHash],
+    ['execution/error_kind', params.error ? 'runtime' : params.status === 'failure' ? 'assertion' : 'none'],
+    ['execution/timestamp', timestamp],
+  ]);
+
+  // Create immutable, BLAKE3-hashed MCard
+  const payloadStr = JSON.stringify(payload, null, 2);
+  const mcard = MCard.create(uri, payloadStr, authorDid, 1, metadata);
+
+  // Commit to studioMCardFs CAS storage
+  try {
+    if (studioMCardFs) {
+      if (typeof (studioMCardFs as any).putCard === 'function') {
+        (studioMCardFs as any).putCard(mcard);
+      } else if (typeof (studioMCardFs as any).writeFile === 'function') {
+        (studioMCardFs as any).writeFile(uri, payloadStr, authorDid);
+      }
+    }
+  } catch (storageErr) {
+    console.warn('Non-fatal: Could not write execution MCard to studioMCardFs:', storageErr);
+  }
+
+  return {
+    id: mcard.hash.toString(),
+    uri,
+    mcard,
+    status: params.status,
+    testCaseTitle: testTitle,
+    stageTimings: params.stageTimings,
+    timestamp: new Date().toLocaleTimeString(),
+    vcardHash: params.vcardHash,
+    payload,
+  };
+}

package/src/services/mcardFileSystemBridge.ts

@@ -0,0 +1,127 @@
+/**
+ * Sovereign MCard File System Access API Bridge (Sprint CR-05)
+ * Canonical Path: src/services/mcardFileSystemBridge.ts
+ *
+ * Facade bridging in-memory MCard Content-Addressed Storage (CAS) with
+ * the host operating system's native filesystem and clipboard.
+ * Delegates low-level picker I/O to src/utils/browserFilePicker.ts and
+ * modularized engines in src/services/bridge/.
+ *
+ * Invariants:
+ * - INV-317-01: Native Picker Priority & Universal Fallback
+ * - INV-317-02: Zero-Leak Blob Disposal Guarantee
+ * - INV-317-03: Silent Cancel Resiliency (AbortError suppression)
+ * - INV-317-04: MIME/Extension Lattice Conformance
+ * - INV-319-01: Immutable CAS Block Retention
+ * - INV-319-02: Bitemporal Provenance Audit Log
+ *
+ * Contract D: <= 120 LOC.
+ */
+
+import { type MCardFileNode, updateStorageTelemetry } from '../stores/mcardStore';
+import {
+  saveBytesViaPickerOrDownload,
+  openFileViaPickerOrInput,
+} from '../utils/browserFilePicker';
+import { getMimeAndExtensionInfo } from './bridge/mimeLattice';
+import { extractMCardBytes } from './bridge/mcardByteExtractor';
+
+// Re-export modular bridge interfaces and services for full backward compatibility
+export {
+  MIME_EXTENSION_LATTICE,
+  getMimeAndExtensionInfo,
+  type PickerTypeOption,
+  type MimeExtensionInfo,
+} from './bridge/mimeLattice';
+export {
+  extractBytesFromMCard,
+  extractMCardBytes,
+} from './bridge/mcardByteExtractor';
+export { copyMCardToClipboard } from './bridge/mcardClipboard';
+export {
+  resealAndReplaceMCard,
+  type ResealResult,
+} from './bridge/mcardResealer';
+export {
+  exportDirectoryToNativeFs,
+  type DirectoryBridgeResult,
+} from './bridge/mcardDirectoryExporter';
+
+export interface FileBridgeResult {
+  success: boolean;
+  cancelled?: boolean;
+  error?: string;
+  bytesWritten?: number;
+  filename?: string;
+  handle?: any;
+}
+
+export interface FileOpenResult {
+  success: boolean;
+  cancelled?: boolean;
+  error?: string;
+  file?: File;
+  bytes?: Uint8Array;
+  content?: string;
+  filename?: string;
+  mimeType?: string;
+}
+
+/**
+ * Saves an MCard to the host file system via Native File System Access API
+ * or programmatic Blob download fallback. Guarantees non-zero bytes written.
+ */
+export async function saveMCardToNativeFs(
+  mcard: MCardFileNode,
+  customFilename?: string
+): Promise<FileBridgeResult> {
+  if (!mcard) {
+    return { success: false, error: 'No active MCard provided for save' };
+  }
+
+  const bytes = await extractMCardBytes(mcard);
+  const target = customFilename || mcard.name || mcard.path || mcard.handle;
+  const mimeInfo = getMimeAndExtensionInfo(target, mcard.mimeType);
+
+  let suggestedName = customFilename || mcard.name || mimeInfo.filename;
+  suggestedName = suggestedName.replace(/:/g, '_');
+  if (mimeInfo.ext && !suggestedName.toLowerCase().endsWith(mimeInfo.ext.toLowerCase())) {
+    suggestedName += mimeInfo.ext;
+  }
+
+  const res = await saveBytesViaPickerOrDownload(
+    bytes,
+    suggestedName,
+    mimeInfo.mime,
+    mimeInfo.pickerTypes
+  );
+
+  if (res.success) {
+    updateStorageTelemetry({
+      lastSavedIso: new Date().toISOString(),
+      isPersistent: true,
+    });
+  }
+
+  return res;
+}
+
+/**
+ * Triggers the OS File Open picker to select a replacement file from disk.
+ */
+export async function openFileFromNativeFs(options?: {
+  acceptedTypes?: string[];
+  mimeDescription?: string;
+}): Promise<FileOpenResult> {
+  const accept = options?.acceptedTypes?.join(',');
+  const pickerTypes = options?.acceptedTypes
+    ? [
+        {
+          description: options.mimeDescription || 'Supported Files',
+          accept: { '*/*': options.acceptedTypes },
+        },
+      ]
+    : undefined;
+
+  return openFileViaPickerOrInput(accept, pickerTypes);
+}

package/src/services/mcardVfs.ts

@@ -0,0 +1,88 @@
+/**
+ * MCard Universal Virtual File System (MCardVFS) — Compatibility Facade
+ * Canonical Path: src/services/mcardVfs.ts
+ * Deliverable: DEL-294-02 (Sprint 294)
+ *
+ * Implements the Universal File System bridge over Content-Addressable Storage.
+ * Indexes the sample knowledge repositories: computable_knowledge/ and assets/.
+ *
+ * Since Sprint 294 this module is a pure re-export facade over the
+ * stratified vfs/ module tree (see src/services/vfs/). The export
+ * surface is frozen (INV-294-01 zero export-signature drift): every
+ * symbol below preserves its pre-refactor name, signature, and type.
+ * New code SHOULD import from the leaf module it needs; existing
+ * callers keep importing here indefinitely.
+ *
+ * Module strata (INV-294-02 module DAG, see tools/guards/check_vfs_module_dag.py):
+ *   vfsCore/vfsUtils (leaves) ← vfsPersistence/vfsSync/vfsHandles ←
+ *   vfsContent/vfsAssets ← vfsVersions/vfsMutations ← vfsBootstrap
+ *   vfsCordis mounts the runtime contract (DEL-294-04).
+ */
+
+// ── Core: CAS singleton (SSOT, INV-294-03) ─────────────────────────────────
+export { studioMCardFs } from './vfs/vfsCore';
+
+// ── Persistence: IndexedDB host coeffect (U0) ──────────────────────────────
+export { hydrateFromIndexedDb, triggerIndexedDbSync } from './vfs/vfsPersistence';
+
+// ── Bootstrap: sample registry & initialization ─────────────────────────────
+export {
+  CANONICAL_SAMPLE_DATA,
+  generateContentHash,
+  initializeMCardVfs,
+} from './vfs/vfsBootstrap';
+export type { VfsEntry } from './vfs/vfsBootstrap';
+
+// ── Handles: PTR indirection ────────────────────────────────────────────────
+export {
+  findMCardByTarget,
+  resolveMCardWithFiber,
+  parseHandleWithFiber,
+  getMediaRawUrl,
+  resolveRemoteMCard,
+} from './vfs/vfsHandles';
+export type { ParameterFiber } from './vfs/vfsHandles';
+
+// ── Content: CAS payload operations (U1) ─────────────────────────────────────
+export {
+  fetchMCardContent,
+  updateMCardContent,
+  saveMCardContent,
+  saveMCardBinaryContent,
+  forkCardToLocalDatabase,
+  fetchMCardByRef,
+} from './vfs/vfsContent';
+export type { MCardRefResult } from './vfs/vfsContent';
+
+// ── Assets: MCard minting (U1→U2) ───────────────────────────────────────────
+export {
+  insertMCardToAssets,
+  base64ToUint8Array,
+  deriveUsefulImageFilename,
+  insertImageToAssets,
+  registerChatImageMCard,
+  enforceMimeExtension,
+} from './vfs/vfsAssets';
+export type { InsertImageOptions } from './vfs/vfsAssets';
+
+// ── Versions: provenance & witness history (U3) ────────────────────────────
+export {
+  getMCardHashHistory,
+  getMCardVersionList,
+  getMCardVersionListDetailed,
+  switchToMCardVersion,
+  restoreMCardVersion,
+} from './vfs/vfsVersions';
+export type { MCardVersionItem, MCardVersionListResult } from './vfs/vfsVersions';
+
+// ── Sync: host federation (Layer-3) ─────────────────────────────────────────
+export { syncMCardVfsWithServer } from './vfs/vfsSync';
+
+// ── Mutations: rename / move / reference propagation (U2) ───────────────────
+export {
+  propagateHandleReferenceUpdate,
+  renameMCardFile,
+  moveMCardFile,
+  createMCardWithReference,
+} from './vfs/vfsMutations';
+export type { MoveResult, ReferencePropagationResult } from './vfs/vfsMutations';