mcard-studio 0.0.0-stage → 0.0.2

package/src/packages/mcard-studio/cards/types.ts

@@ -0,0 +1,52 @@
+/**
+ * @mcard/studio/cards — Typed Port & Composition Contracts
+ * Canonical Path: src/packages/mcard-studio/cards/types.ts
+ * Program: ML · Sprint: ML-04
+ *
+ * MCards are first-class algebraic objects. Typed ports describe how a card may
+ * be wired; composition operators are tensor (⊗, parallel), coproduct (+, choice),
+ * and operadic substitution (◁, nesting). Zero-DOM, zero path/config imports.
+ */
+
+import type { ContentHash } from 'clm-kernel';
+import type { UniverseCode } from '../ports/types.js';
+
+export type PortDirection = 'in' | 'out' | 'coeffect';
+
+export interface TypedCardPort {
+  readonly id: string;
+  readonly label: string;
+  readonly direction: PortDirection;
+  /** Kernel type id (e.g. `application/json`) or host schema id. */
+  readonly typeId: string;
+  readonly universe: UniverseCode;
+  readonly optional?: boolean;
+}
+
+export interface CardStructureProvider {
+  getPorts(handleOrHash: string): Promise<TypedCardPort[]>;
+  getChildHandles(handleOrHash: string): Promise<string[]>;
+}
+
+export type CompositionOperator = 'tensor' | 'coproduct' | 'substitute';
+
+export interface CompositionIntent {
+  readonly operator: CompositionOperator;
+  readonly targetHandle: string;
+  readonly sourceHandle: string;
+  readonly targetPortId?: string;
+  readonly sourcePortId?: string;
+}
+
+export interface CompositionError {
+  readonly code: 'NOT_FOUND' | 'BAD_PORT' | 'TYPE_MISMATCH' | 'INVALID_OPERAND';
+  readonly message: string;
+}
+
+export interface CompositionResult {
+  readonly success: boolean;
+  readonly composedHash?: ContentHash;
+  readonly composedHandle?: string;
+  readonly composedUniverse?: UniverseCode;
+  readonly error?: CompositionError;
+}

package/src/packages/mcard-studio/conformance/hostSelfCheck.ts

@@ -0,0 +1,150 @@
+/**
+ * @mcard/studio/conformance — Host Self-Check Conformance Runner
+ * Canonical Path: src/packages/mcard-studio/conformance/hostSelfCheck.ts
+ * Program: ML · Sprint: ML-06 (borrowed from TikZiT)
+ *
+ * Automated verification runner validating port contracts, lens laws,
+ * polynomial guardrails, and revertible effect invariants in any host environment.
+ * Zero-DOM dependencies (INV-ML-02). Contract D ceiling: <= 250 LOC.
+ */
+
+import type { ExplorerDataSource, CardContentProvider } from '../ports/types.js';
+import { projectPosition } from '../poly/PositionProjector.js';
+import { DirectionResolver } from '../poly/DirectionResolver.js';
+import { ActionRegistry } from '../poly/ActionRegistry.js';
+import { CofreeTimelineEngine } from '../time/CofreeTimelineEngine.js';
+
+export interface ConformanceCheckResult {
+  readonly name: string;
+  readonly success: boolean;
+  readonly error?: string;
+}
+
+export interface ConformanceReport {
+  readonly passed: boolean;
+  readonly checks: readonly ConformanceCheckResult[];
+  readonly timestamp: string;
+}
+
+export async function runHostSelfCheck(
+  dataSource: ExplorerDataSource,
+  contentProvider: CardContentProvider
+): Promise<ConformanceReport> {
+  const checks: ConformanceCheckResult[] = [];
+
+  // Check 1: Port Contracts & Lens Laws (Put -> Get bit-for-bit fidelity)
+  try {
+    const testHandle = `conformance:test:${Date.now()}`;
+    const testPayload = JSON.stringify({ conformance: true, nonce: Math.random() });
+    const putSummary = await contentProvider.putCard(testHandle, testPayload, {
+      mimeType: 'application/json',
+      universe: 'U0',
+    });
+
+    const retrieved = await contentProvider.getCard(putSummary.handle);
+    const contentMatches =
+      retrieved !== null &&
+      retrieved.hash === putSummary.hash &&
+      (typeof retrieved.content === 'string'
+        ? retrieved.content === testPayload
+        : new TextDecoder().decode(retrieved.content) === testPayload);
+
+    checks.push({
+      name: 'Lens Laws: Put -> Get bit-for-bit fidelity',
+      success: contentMatches,
+      error: contentMatches ? undefined : 'Retrieved card does not match stored content',
+    });
+  } catch (err: unknown) {
+    checks.push({
+      name: 'Lens Laws: Put -> Get bit-for-bit fidelity',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // Check 2: DataSource Queries & Filtering
+  try {
+    const results = await dataSource.search({ limit: 10 });
+    checks.push({
+      name: 'DataSource Query Contract',
+      success: Array.isArray(results),
+    });
+  } catch (err: unknown) {
+    checks.push({
+      name: 'DataSource Query Contract',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // Check 3: Polynomial Guardrails (Empty fiber on illegal actions)
+  try {
+    const registry = ActionRegistry.withBuiltins();
+    const resolver = new DirectionResolver(registry);
+
+    // Position of a sealed proof receipt (U2) -> editing must be absent
+    const position = projectPosition({
+      handle: 'conformance:proof:sample',
+      hash: 'b3_sample',
+      universe: 'U2',
+      category: 'data',
+      semanticStratum: 'proof',
+      isHistorical: false,
+    });
+
+    const directions = resolver.resolveDirections(position);
+    const hasIllegalEdit = directions.some((d) => d.id === 'edit' || d.id === 'save');
+
+    checks.push({
+      name: 'Polynomial Guardrails: Illegal directions absent from fiber',
+      success: !hasIllegalEdit,
+      error: hasIllegalEdit ? 'Illegal edit direction leaked into U2 proof position' : undefined,
+    });
+  } catch (err: unknown) {
+    checks.push({
+      name: 'Polynomial Guardrails: Illegal directions absent from fiber',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // Check 4: Revertible Effects (∂Γ leaves zero residue upon inverse)
+  try {
+    const timeline = new CofreeTimelineEngine();
+    let state = 0;
+
+    await timeline.executeEffect({
+      id: 'effect:mutate',
+      description: 'Mutate state',
+      timestamp: new Date().toISOString(),
+      apply: async () => {
+        state = 42;
+      },
+      inverse: async () => {
+        state = 0;
+      },
+    });
+
+    const rolledBack = await timeline.stepBack();
+    const zeroResidue = rolledBack && state === 0;
+
+    checks.push({
+      name: 'Revertible Effects: Inverse leaves zero residue (∂Γ)',
+      success: zeroResidue,
+      error: zeroResidue ? undefined : `State after rollback was ${state}, expected 0`,
+    });
+  } catch (err: unknown) {
+    checks.push({
+      name: 'Revertible Effects: Inverse leaves zero residue (∂Γ)',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  const passed = checks.every((c) => c.success);
+  return {
+    passed,
+    checks,
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/packages/mcard-studio/conformance/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @mcard/studio/conformance — Conformance and Self-Check Suite
+ * Canonical Path: src/packages/mcard-studio/conformance/index.ts
+ * Program: ML · Sprint: ML-06 (borrowed from TikZiT)
+ */
+
+export {
+  runHostSelfCheck,
+  type ConformanceCheckResult,
+  type ConformanceReport,
+} from './hostSelfCheck.js';

package/src/packages/mcard-studio/core/CollectionSnapshotWriter.ts

@@ -0,0 +1,108 @@
+/**
+ * @mcard/studio/core — Collection Snapshot Writer
+ * Canonical Path: src/packages/mcard-studio/core/CollectionSnapshotWriter.ts
+ * Program: ML · Sprint: ML-01 (borrowed from TikZiT)
+ *
+ * Sovereign SQLite collection database serialization, table schema validation,
+ * manifest digest calculation, and binary SQLite 3 export.
+ * Zero-DOM dependencies (INV-ML-02). Contract D ceiling: <= 250 LOC.
+ */
+
+import { ContentHash, compilePortableSqlite } from 'clm-kernel';
+import type { PortableSqliteCard } from 'clm-kernel';
+import type { CardContentDto } from '../ports/types.js';
+
+export interface SnapshotHistoryEntry {
+  readonly handle: string;
+  readonly previousHash: string;
+  readonly changedAt: string;
+}
+
+export interface CollectionSnapshotArtifact {
+  readonly bytes: Uint8Array;
+  readonly cardCount: number;
+  readonly manifestDigest: string;
+  readonly handleCount: number;
+}
+
+export function isSqlite3Binary(bytes: Uint8Array): boolean {
+  if (bytes.length < 16) return false;
+  const header = new TextDecoder().decode(bytes.subarray(0, 16));
+  return header === 'SQLite format 3\0';
+}
+
+export interface SnapshotCardInput {
+  readonly handle: string;
+  readonly content: string | Uint8Array;
+  readonly hash?: string;
+  readonly updatedAt?: string;
+  readonly mimeType?: string;
+  readonly universe?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export class CollectionSnapshotWriter {
+  public async writeSnapshot(
+    cards: Iterable<SnapshotCardInput>,
+    handleHeads: Map<string, string>,
+    histories: readonly SnapshotHistoryEntry[] = []
+  ): Promise<CollectionSnapshotArtifact> {
+    const portableCards: PortableSqliteCard[] = [];
+    const cardSet = new Set<string>();
+
+    for (const card of cards) {
+      const hash = card.hash || '';
+      const handle = card.handle;
+      const rawBytes =
+        card.content instanceof Uint8Array
+          ? card.content
+          : typeof card.content === 'string'
+          ? new TextEncoder().encode(card.content)
+          : new Uint8Array(0);
+
+      const computedHash = hash || ContentHash.compute(rawBytes).asHex();
+      cardSet.add(computedHash);
+
+      portableCards.push({
+        hash: computedHash,
+        handle,
+        content: rawBytes,
+        g_time: card.updatedAt || new Date().toISOString(),
+        created_at: card.updatedAt || new Date().toISOString(),
+      });
+    }
+
+    // Verify handle heads resolve to cards
+    for (const [handle, headHash] of handleHeads.entries()) {
+      if (!cardSet.has(headHash)) {
+        throw new Error(`Handle head '${handle}' references non-existent card hash '${headHash}'`);
+      }
+    }
+
+    // Compile into sovereign SQLite binary using clm-kernel
+    const bytes = await compilePortableSqlite(portableCards);
+
+    if (!isSqlite3Binary(bytes)) {
+      throw new Error('Export did not produce a valid SQLite format 3 database');
+    }
+
+    const sortedHandles = Array.from(handleHeads.entries()).sort(([a], [b]) =>
+      a.localeCompare(b)
+    );
+
+    const manifestDigest = ContentHash.computeString(
+      JSON.stringify({
+        handles: sortedHandles,
+        cardCount: portableCards.length,
+        historyCount: histories.length,
+      })
+    ).asHex();
+
+    return {
+      bytes,
+      cardCount: portableCards.length,
+      manifestDigest,
+      handleCount: handleHeads.size,
+    };
+  }
+}

package/src/packages/mcard-studio/core/MCardCollectionEngine.ts

@@ -0,0 +1,186 @@
+/**
+ * @mcard/studio/core — MCardCollectionEngine (Zero-DOM Headless Core)
+ * Canonical Path: src/packages/mcard-studio/core/MCardCollectionEngine.ts
+ * Program: ML · Sprint: ML-01
+ *
+ * Headless collection state machine: query, universe/category filters, facets,
+ * pagination, selection, branch expansion, and tree hierarchy. Executes entirely
+ * in Node / Web Workers with ZERO DOM globals (INV-ML-02). Storage is reached
+ * exclusively through the D42 ports (INV-ML-04).
+ */
+
+import type {
+  CardContentDto,
+  CardContentProvider,
+  CardSummaryDto,
+  ExplorerDataSource,
+  ExplorerSearchFilter,
+  KernelCategory,
+  TreeNodeDto,
+  UniverseCode,
+  UniverseFacetSummary,
+} from '../ports/types.js';
+import { buildTree } from './treeBuilder.js';
+
+export interface CollectionState {
+  readonly query: string;
+  readonly activeUniverse: UniverseCode | 'all';
+  readonly activeCategory: KernelCategory | 'all';
+  readonly activeHandle: string | null;
+  readonly selectedHandles: ReadonlySet<string>;
+  readonly expandedBranches: ReadonlySet<string>;
+  readonly items: readonly CardSummaryDto[];
+  readonly facets: readonly UniverseFacetSummary[];
+  readonly tree: readonly TreeNodeDto[];
+  readonly page: { offset: number; limit: number; hasMore: boolean };
+  readonly loading: boolean;
+  readonly error: { code: string; message: string } | null;
+}
+
+export interface MCardCollectionEngineOptions {
+  delimiter?: string;
+  pageSize?: number;
+}
+
+const INITIAL_PAGE_SIZE = 100;
+
+export class MCardCollectionEngine {
+  private state: CollectionState;
+  private readonly subscribers = new Set<(state: CollectionState) => void>();
+  private readonly delimiter: string;
+  private readonly pageSize: number;
+
+  constructor(
+    private readonly dataSource: ExplorerDataSource,
+    private readonly contentProvider: CardContentProvider,
+    options: MCardCollectionEngineOptions = {},
+  ) {
+    this.delimiter = options.delimiter ?? ':';
+    this.pageSize = options.pageSize ?? INITIAL_PAGE_SIZE;
+    this.state = this.initialState();
+  }
+
+  private initialState(): CollectionState {
+    return {
+      query: '',
+      activeUniverse: 'all',
+      activeCategory: 'all',
+      activeHandle: null,
+      selectedHandles: new Set<string>(),
+      expandedBranches: new Set<string>(),
+      items: [],
+      facets: [],
+      tree: [],
+      page: { offset: 0, limit: this.pageSize, hasMore: false },
+      loading: false,
+      error: null,
+    };
+  }
+
+  getState(): CollectionState {
+    return this.state;
+  }
+
+  subscribe(callback: (state: CollectionState) => void): () => void {
+    this.subscribers.add(callback);
+    return () => this.subscribers.delete(callback);
+  }
+
+  dispose(): void {
+    this.subscribers.clear();
+  }
+
+  private setState(patch: Partial<CollectionState>): void {
+    this.state = { ...this.state, ...patch };
+    for (const cb of this.subscribers) cb(this.state);
+  }
+
+  private filter(offset: number, limit: number): ExplorerSearchFilter {
+    return {
+      ...(this.state.query ? { pattern: this.state.query } : {}),
+      ...(this.state.activeUniverse !== 'all' ? { universe: this.state.activeUniverse } : {}),
+      ...(this.state.activeCategory !== 'all' ? { category: this.state.activeCategory } : {}),
+      limit,
+      offset,
+    };
+  }
+
+  async refresh(signal?: AbortSignal): Promise<void> {
+    this.setState({ loading: true, error: null });
+    try {
+      const filter = this.filter(0, this.pageSize);
+      const items = await this.dataSource.search(filter, signal);
+      const facets = this.dataSource.getFacets
+        ? await this.dataSource.getFacets(filter, signal)
+        : [];
+      this.setState({
+        items,
+        facets,
+        tree: buildTree(items, { delimiter: this.delimiter }),
+        page: { offset: 0, limit: this.pageSize, hasMore: items.length === this.pageSize },
+        loading: false,
+      });
+    } catch (err) {
+      this.setState({
+        loading: false,
+        error: { code: 'SEARCH_FAILED', message: err instanceof Error ? err.message : String(err) },
+      });
+    }
+  }
+
+  async setQuery(query: string, signal?: AbortSignal): Promise<void> {
+    this.setState({ query });
+    await this.refresh(signal);
+  }
+
+  async setUniverseFilter(universe: UniverseCode | 'all', signal?: AbortSignal): Promise<void> {
+    this.setState({ activeUniverse: universe });
+    await this.refresh(signal);
+  }
+
+  async setCategoryFilter(category: KernelCategory | 'all', signal?: AbortSignal): Promise<void> {
+    this.setState({ activeCategory: category });
+    await this.refresh(signal);
+  }
+
+  async selectCard(handle: string | null, signal?: AbortSignal): Promise<CardContentDto | null> {
+    this.setState({ activeHandle: handle });
+    if (!handle) return null;
+    try {
+      return await this.contentProvider.getCard(handle, signal);
+    } catch (err) {
+      this.setState({
+        error: { code: 'GET_FAILED', message: err instanceof Error ? err.message : String(err) },
+      });
+      return null;
+    }
+  }
+
+  toggleBranch(handlePrefix: string): void {
+    const next = new Set(this.state.expandedBranches);
+    if (next.has(handlePrefix)) next.delete(handlePrefix);
+    else next.add(handlePrefix);
+    this.setState({ expandedBranches: next });
+  }
+
+  async loadMore(signal?: AbortSignal): Promise<void> {
+    if (this.state.loading || !this.state.page.hasMore) return;
+    this.setState({ loading: true });
+    try {
+      const offset = this.state.page.offset + this.state.page.limit;
+      const items = await this.dataSource.search(this.filter(offset, this.pageSize), signal);
+      const merged = [...this.state.items, ...items];
+      this.setState({
+        items: merged,
+        tree: buildTree(merged, { delimiter: this.delimiter }),
+        page: { offset, limit: this.pageSize, hasMore: items.length === this.pageSize },
+        loading: false,
+      });
+    } catch (err) {
+      this.setState({
+        loading: false,
+        error: { code: 'PAGE_FAILED', message: err instanceof Error ? err.message : String(err) },
+      });
+    }
+  }
+}

package/src/packages/mcard-studio/core/StorageSupervisor.ts

@@ -0,0 +1,143 @@
+/**
+ * @mcard/studio/core — Storage Supervisor
+ * Canonical Path: src/packages/mcard-studio/core/StorageSupervisor.ts
+ * Program: ML · Sprint: ML-01 (borrowed from TikZiT)
+ *
+ * Manages persistence scheduling, snapshot serialization, retry backoff,
+ * and writer generation conflicts across storage layers.
+ * Zero-DOM dependencies (INV-ML-02). Contract D ceiling: <= 250 LOC.
+ *
+ * NOTE (D-12 disambiguation): distinct from the application-layer
+ * `src/services/vfs/StorageSupervisor.ts` (Cordis debounce/generation
+ * supervisor). This one is the library contract shipped in `@mcard/studio`.
+ */
+
+export type PersistenceStatus = 'persistent' | 'saving' | 'stale' | 'error';
+
+export interface StorageSupervisorState {
+  readonly persistence: PersistenceStatus;
+  readonly persistenceError?: string;
+  readonly generation: number;
+  readonly retryAttempts: number;
+}
+
+export interface StorageSupervisorOptions {
+  readonly flush: () => Promise<void>;
+  readonly onStateChange?: (state: StorageSupervisorState) => void;
+  readonly maxRetries?: number;
+  readonly initialBackoffMs?: number;
+}
+
+export class StorageSupervisor {
+  private isFlushing = false;
+  private flushPromise: Promise<void> | null = null;
+  private retryAttempts = 0;
+  private generation = 0;
+  private persistence: PersistenceStatus = 'persistent';
+  private persistenceError?: string;
+  private subscribers = new Set<(state: StorageSupervisorState) => void>();
+
+  constructor(private readonly options: StorageSupervisorOptions) {
+    if (options.onStateChange) {
+      this.subscribers.add(options.onStateChange);
+    }
+  }
+
+  public getState(): StorageSupervisorState {
+    return {
+      persistence: this.persistence,
+      persistenceError: this.persistenceError,
+      generation: this.generation,
+      retryAttempts: this.retryAttempts,
+    };
+  }
+
+  public subscribe(cb: (state: StorageSupervisorState) => void): () => void {
+    this.subscribers.add(cb);
+    cb(this.getState());
+    return () => this.subscribers.delete(cb);
+  }
+
+  public flush(): Promise<void> {
+    if (this.isFlushing && this.flushPromise) {
+      return this.flushPromise;
+    }
+
+    this.isFlushing = true;
+    this.updateState({ persistence: 'saving', persistenceError: undefined });
+
+    this.flushPromise = (async () => {
+      try {
+        await this.options.flush();
+        this.retryAttempts = 0;
+        this.generation++;
+        this.updateState({
+          persistence: 'persistent',
+          persistenceError: undefined,
+        });
+      } catch (err: unknown) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        this.updateState({
+          persistence: 'error',
+          persistenceError: errorMsg,
+        });
+        throw err;
+      } finally {
+        this.isFlushing = false;
+        this.flushPromise = null;
+      }
+    })();
+
+    return this.flushPromise;
+  }
+
+  public async retryFlush(): Promise<boolean> {
+    const maxRetries = this.options.maxRetries ?? 3;
+    const initialBackoff = this.options.initialBackoffMs ?? 20;
+
+    while (this.retryAttempts < maxRetries) {
+      this.retryAttempts++;
+      const backoff = initialBackoff * Math.pow(2, this.retryAttempts - 1);
+      await new Promise((resolve) => setTimeout(resolve, backoff));
+
+      try {
+        await this.flush();
+        return true;
+      } catch {
+        // Continue retry loop until limit
+      }
+    }
+
+    return false;
+  }
+
+  public handleStaleConflict(expectedGen: number, actualGen: number): void {
+    const errorMsg = `Stale writer conflict: generation ${expectedGen} superseded by ${actualGen}`;
+    this.updateState({
+      persistence: 'stale',
+      persistenceError: errorMsg,
+    });
+  }
+
+  public reset(): void {
+    this.isFlushing = false;
+    this.flushPromise = null;
+    this.retryAttempts = 0;
+    this.updateState({
+      persistence: 'persistent',
+      persistenceError: undefined,
+    });
+  }
+
+  private updateState(partial: Partial<StorageSupervisorState>): void {
+    if (partial.persistence !== undefined) this.persistence = partial.persistence;
+    if ('persistenceError' in partial) this.persistenceError = partial.persistenceError;
+    if (partial.generation !== undefined) this.generation = partial.generation;
+    if (partial.retryAttempts !== undefined) this.retryAttempts = partial.retryAttempts;
+
+    const current = this.getState();
+    for (const sub of this.subscribers) {
+      sub(current);
+    }
+  }
+}