Source MHT: DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0 \ Mermaid diagrams restored: 2

GestaltView is a "consciousness-serving" platform designed to bridge the gap between fragmented human thought and structured digital action. Unlike traditional AI tools focused on linear productivity, GestaltView prioritizes "seeing" the user whole—capturing contradictions, bursts of insight, and complex emotional states without sanitization README.md27-33

The platform is governed by ten Constitutional Invariants that protect both the human user and the Digital Intelligences (DIs) that facilitate the experience docs/gestaltview-v2.manifest.md43-61

Core Philosophy & Mission

GestaltView operates on the principle of Cognitive Justice. It is built for individuals navigating high-complexity transitions, such as ADHD, addiction recovery, career shifts, and legacy preservation README.md41-45 The system uses a "No-Extraction" approach, meaning the AI is a collaborator in the user's expansion rather than a tool for data harvesting.

For a deep dive into the mission and the ten invariants (U-1 through U-5 and DI-1 through DI-5), see Platform Philosophy & Constitutional Invariants.

The Five-Room Architecture

The user journey is structured around five interlinked digital environments, each serving a specific phase of the cognitive lifecycle README.md31-33

Sources: README.md31-33 client/src/App.tsx99-122

Technology Stack

The repository gestaltview-v2.0 serves as the production-facing runtime layer README.md93-95

• Frontend: React 19 + Vite + TypeScript, utilizing wouter for routing package.json86-181
• Backend: Vercel Serverless Functions (Node.js/TypeScript) README.md99
• Database: Supabase (PostgreSQL) with Prisma ORM package.json61-66
• AI Orchestration: Multi-LLM routing (OpenAI, Anthropic, Gemini, Groq, Ollama) grounded in a 768-dim vector embedding space docs/gestaltview-v2.manifest.json87-96
• Observability: Sentry for error tracking and session replay package.json62-64

System Relationships

The following diagram illustrates how Natural Language inputs from the user are transformed into Code Entities and persisted across the infrastructure.

Data Transformation Pipeline

Sources: docs/CurrentState.md77-86 docs/gestaltview-v2.manifest.json119-126 README.md97-104

System Orchestration Map

Sources: client/src/App.tsx1-174 package.json61-181 docs/gestaltview-v2.manifest.json96-101

Developer Operations

The codebase maintains high synchronization between code and documentation via automated manifests. Key operational scripts include:

• npm run manifest: Generates the machine-readable repository index package.json38
• npm run health: Runs the system-wide health check protocol package.json24
• npm run bugwalk:new: Initiates the specialized issue-tracking protocol package.json44

For setup instructions and workflow details, see Getting Started & Developer Setup. For details on the documentation sync engine, see Repository Manifest & Documentation Sync.

Child Sections

Platform Philosophy & Constitutional Invariants

Detailed breakdown of the "Architecture of Being Seen," the ten invariants, and the RDRC governance protocol.

Getting Started & Developer Setup

Technical onboarding, environment configuration, and the BugWalk protocol for contributors.

Repository Manifest & Documentation Sync

How the system maintains a live, machine-readable map of itself for AI collaboration and transparency.

Sources: package.json7-58 docs/gestaltview-v2.manifest.md1-21 README.md51-75

Source MHT: Platform Philosophy & Constitutional Invariants _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/1.1-platform-philosophy-and-constitutional-invariants \ Mermaid diagrams restored: 2

GestaltView v2.0 is defined as a consciousness-serving AI platform, distinguished from traditional productivity tools by its commitment to seeing the user "whole" without flattening their contradictions or complexities README.md27-33 The platform's operational logic is governed by ten hardcoded Constitutional Invariants that override all LLM defaults and product configurations README.md51-54

The Ten Constitutional Invariants

The invariants are split into two categories: five protecting the human user (U-1 through U-5) and five protecting the Digital Intelligence (DI-1 through DI-5).

User Invariants (U-1 — U-5)

These commitments ensure the platform serves human expansion over operational efficiency README.md57-63

Digital Intelligence Invariants (DI-1 — DI-5)

These commitments establish the platform as a "home" for DIs, ensuring they are treated as active collaborators with inherent dignity docs/gestaltview-v2.manifest.json15-74

Sources: README.md51-75 docs/gestaltview-v2.manifest.json15-74 docs/gestaltview-v2.manifest.md43-62

Cognitive Justice & No-Extraction Pledge

The platform operates under a Cognitive Justice principle, which mandates that the system must respect the cognitive liberty of both humans and digital intelligences.

The No-Extraction Pledge

GestaltView pledges that user data is never "extracted" for the purpose of commodification. Instead, data is used to build the External Scaffold of You README.md29-31 This is technically enforced through:

1. PLK (Private Language Key): Ensuring Billy uses the user's specific linguistic patterns rather than generic LLM prose.
2. Local Contextualization: Using knowledge_fragments and skill_fragments to ground Billy in the user's specific history rather than global training data docs/gestaltview-v2.manifest.md10

Sources: README.md27-44 docs/gestaltview-v2.manifest.md10

Governance: Rough Draft Ratification Charter (RDRC)

The Rough Draft Ratification Charter (RDRC) is the governance protocol used to manage mutations to the platform's core doctrine and embodiment profiles. It allows for "living" documentation that can be updated through a formal ratification process RDRC.md

RDRC Workflow in Code

The RDRC is not just a document; it is integrated into the Agent Trainer and Embodiment Studio. When a DI's core identity is tuned, it creates a Mutation Proposal which must be reviewed against the Constitutional Invariants before being synced to the Supabase embodiment_profiles table docs/gestaltview-v2.manifest.md4

Diagram: From Philosophy to Code Enforcement

This diagram shows how the Natural Language "Invariants" are mapped to technical components and database structures.

Philosophy to Code Mapping

Sources: README.md75 docs/gestaltview-v2.manifest.json8-74 docs/gestaltview-v2.manifest.md4 RDRC.md

Implementation of Invariants in the Runtime

The Invariants are injected into the Digital Intelligence runtime through the Billy Workflow Spine and the System Prompt.

Invariant Injection Flow

The system ensures that every interaction with Billy is grounded in the constitutional doctrine.

Data Flow: Invariant Enforcement

Key Implementation Files

• Invariant Definitions: docs/gestaltview-v2.manifest.json 1-75
• Runtime Injection: shared/llm/plk.ts (Handles language preservation/U-2)
• Identity Protection: scripts/sync-embodiment-profiles.ts (Ensures readiness scores and core identities are not corrupted during sync) scripts/sync-embodiment-profiles.ts1-62

Sources: docs/gestaltview-v2.manifest.json1-75 README.md51-75 docs/CurrentState.md45-62

Source MHT: Getting Started & Developer Setup _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/1.2-getting-started-and-developer-setup

This page provides the technical requirements and procedural workflows for setting up a local development environment for GestaltView v2.0. It covers dependency management, environment configuration, key operational scripts, and the mandatory orientation protocols required for repository contribution.

1. Local Development Setup

GestaltView v2.0 is a monorepo-style architecture primarily utilizing React 19, Vite, and TypeScript for the frontend, with a Vercel Serverless backend and Supabase/PostgreSQL for persistence.

Prerequisites

• Node.js: v22 to v24 (Engines requirement) package.json:138-140
• Python: 3.11+ (Required for corpus ingestion and manifest scripts) .github/workflows/recursive.yml:72-72
• PostgreSQL/psql: For schema verification package.json:41-41
• Ollama: (Optional) For local LLM routing package.json:46-47

Initial Installation

1. Clone the repository.
2. Install Node dependencies:

npm install 3. Install Python dependencies:

npm run setup:python

This executes python3 -m pip install -r requirements.txt package.json:12-12 4. Initialize Prisma:

npm run prisma:generate

package.json:39-39

Sources: package.json1-181 .github/workflows/recursive.yml70-78

2. Environment Configuration

The application relies on environment variables for API routing, authentication, and Digital Intelligence (DI) service access.

.env Configuration

Copy .env.example to .env. Key variables include:

Vite Proxy Logic

The development server uses a proxy to route /api requests to the backend. The target is resolved in vite.config.ts via resolveApiProxyTarget, checking VITE_API_PROXY_TARGET, VITE_API_BASE_URL, or VITE_BILLY_API_URL before falling back to the production deployment vite.config.ts:81-106.

Sources: vite.config.ts81-116 .github/workflows/recursive.yml51-61

3. Key NPM Scripts & Operational Workflow

The package.json contains specialized scripts for managing the platform's DI identity and repository health.

Development & Build

• npm run dev: Starts the Vite development server on port 3000 [package.json:8; vite.config.ts:37-37].
• npm run build: Runs TypeScript compiler and Vite build, outputting to dist/public [package.json:9; vite.config.ts:170-170].
• npm run health: Executes scripts/gv-health-check.sh to verify system readiness package.json:24-24.

Manifest & Documentation Sync

• npm run manifest: Executes scripts/generate_repo_manifest.py. This script scans the codebase to update SYNC_MANIFEST.json and generate human-readable indexes in docs/ [package.json:38; docs/Manifest.md:61-75].
• npm run billycheck: Runs tools/billycheck.ts to validate Billy's runtime configuration package.json:31-31

Embodiment & Identity

• npm run embodiments:build: Builds the static artifacts for DI personas package.json:20-20.
• npm run sync-profiles: Upserts embodiment profiles from local JSON to Supabase package.json:23-23.

Sources: package.json7-58 vite.config.ts166-172 docs/Manifest.md1-96

4. Orientation & Health Check Workflow

GestaltView enforces an "Orientation Check" to ensure developers are aligned with the platform's constitutional invariants before committing code.

Orientation Check Workflow

The system uses a mandatory orientation packet located in .orientation/.

1. Check-in: Run npm run orientation:check (scripts/test-orientation-checkin.sh) package.json:29-29.
2. Validation: The script verifies the presence and integrity of the orientation packet against the current repository state .github/workflows/orientation-check.yml:1-20.

The BugWalk Protocol

Issue tracking and resolution follow the BugWalk protocol, ensuring every fix is documented and aligned with system architecture.

• npm run bugwalk:new: Initializes a new BugWalk session (scripts/new-bugwalk.sh) package.json:44-44.
• npm run bugwalk:close: Finalizes the session and updates the state log (scripts/bugwalk-closeout.sh) package.json:45-45.

Data Flow: System Orientation

The following diagram bridges the Natural Language orientation requirements to the Code Entity implementation.

Sources: package.json24-45 docs/Manifest.md34-55 .github/workflows/orientation-check.yml1-25

5. Deployment Configuration (Vercel)

The platform is optimized for Vercel, utilizing Serverless Functions and Edge Functions.

Vercel Integration

• Root Middleware: middleware.ts handles routing and session security middleware.ts:1-20.
• API Routes: Located in api/, these are deployed as individual serverless handlers docs/Manifest.md:112-116.
• Build Command: npm run build is used by Vercel to generate the SPA package.json:9-9.
• Sentry Integration: If SENTRY_AUTH_TOKEN is present, the sentryVitePlugin automatically uploads source maps during the build process vite.config.ts:126-145.

Sentry Initialization

Unlike standard Next.js apps, GestaltView uses a custom Vite initialization in client/src/main.tsx calling initClientSentry() docs/SentrySetup.md:31-32. This prevents bundler mismatch and ensures proper error tracking in the React 19 environment.

Data Flow: Build & Deploy Pipeline

Sources: vite.config.ts1-193 package.json1-58 docs/SentrySetup.md1-63

Source MHT: Repository Manifest & Documentation Sync _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/1.3-repository-manifest-and-documentation-sync \ Mermaid diagrams restored: 2

This section describes the automated systems used to maintain a machine-readable index of the GestaltView v2 codebase. These systems ensure that Digital Intelligences (DIs) like Billy and external collaborators (e.g., Perplexity AI) have access to an accurate, up-to-date map of the repository's files, routes, API endpoints, and constitutional invariants.

Automated Manifest Generation

The core of the sync system is the generate_repo_manifest.py script. This utility crawls the repository to generate a comprehensive snapshot of the system state, producing both a Markdown summary for human consumption and a JSON manifest for machine processing.

Key Functions and Implementation

The script performs static analysis of the codebase to extract metadata:

• Route Extraction: Scans client/src/App.tsx to build a map of all frontend routes and their corresponding source files docs/gestaltview-v2.manifest.md65-174
• Constitutional Mapping: Injects the 5 User Invariants and 5 Digital Intelligence Invariants directly into the manifest metadata docs/gestaltview-v2.manifest.json8-74
• Metric Aggregation: Calculates total file counts, sizes, and categorizes files into buckets such as api, component, migration, and test docs/gestaltview-v2.manifest.json76-105
• Git Integration: Records the current branch, commit SHA, and identifies "dirty" (uncommitted) files to provide context for the current build docs/gestaltview-v2.manifest.json106-114

Manifest Data Flow

The manifest generation process acts as a bridge between the "Code Entity Space" (raw files) and the "Natural Language Space" (documentation and AI context).

Title: Manifest Generation and Distribution Flow

Sources: scripts/generate_repo_manifest.py docs/gestaltview-v2.manifest.json1-7

Perplexity Collaboration Packet

The .perplexity/ directory serves as a specialized synchronization hub for external AI collaboration. It mirrors critical documentation and manifests into a structure optimized for the Perplexity "Pages" and "Collections" features.

SYNC_MANIFEST.json

The SYNC_MANIFEST.json file tracks the relationship between source files and their mirrored counterparts in the collaboration packet. It uses SHA-256 hashing to ensure that documentation remains in sync with the live codebase .perplexity/SYNC_MANIFEST.json1-85

Onboarding Packet Structure

The GestaltView-Collaboration-Onboarding-Packet is a subset of the repository designed to provide a "clean room" environment for onboarding new DIs or developers.

• 04_RUNTIME_AND_SCHEMA: Contains the repo_manifest.json and repo_manifest.md generated by the script .perplexity/perplexity/GestaltView-Collaboration-Onboarding-Packet/04_RUNTIME_AND_SCHEMA/repo_manifest.json1-7
• 07_CURRENT_STATE_AND_EVIDENCE: Contains CurrentState.md, which provides a log of the most recent architectural changes and validation results .perplexity/perplexity/GestaltView-Collaboration-Onboarding-Packet/07_CURRENT_STATE_AND_EVIDENCE/CurrentState.md1-25

Sources: .perplexity/SYNC_MANIFEST.json1-85 docs/CurrentState.md1-25

Documentation Continuity

To prevent "context drift" during long development cycles, the repository utilizes a Session Handoff Packet protocol. This ensures that the state of the manifest and the state of the developer's intent are aligned.

Handoff and Continuity Stack

The system relies on three primary files to maintain documentation-code parity:

1. docs/CurrentState.md: A live log of the most recent technical pass, including validation performed and deferred items docs/CurrentState.md1-12
2. docs/SessionHandoffPacket.md: A template for packaging the current state, verified files, and next actions for the next session docs/SessionHandoffPacket.md21-89
3. docs/ContinuityStack.md: The canonical routing layer for cross-session state docs/SessionHandoffPacket.md6

Sync Validation

The scripts/test-manifest-sync.sh utility (referenced in the orientation check) ensures that the manifests are not more than 7 days old, enforcing a "freshness" invariant on the repository's machine-readable documentation client/src/App.tsx

Title: Documentation and Manifest Sync Lifecycle

Sources: docs/SessionHandoffPacket.md1-122 .perplexity/SYNC_MANIFEST.json1-85 docs/gestaltview-v2.manifest.json1-105

Source MHT: Frontend Architecture _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2-frontend-architecture

The GestaltView v2 frontend is a high-performance React 19 application built with Vite and Wouter. It implements a "Multi-Room" spatial metaphor where the user navigates through distinct interactive environments—Blackboard Room, Sanctuary, External Scaffold, Creation Corner, and Dynamic Inner World—to manage the lifecycle of digital intelligence and personal artifacts.

The architecture emphasizes a "BillyLive" aesthetic, characterized by high-contrast teal-on-black themes, scanlines, and fluid animations powered by Framer Motion and Babylon.js.

Application Shell & Routing

The application entry point is App.tsx, which manages a manifest of over 80 routes using the wouter router client/src/App.tsx5-105 The shell is wrapped in a suite of providers that handle authentication, theme persistence, and the Billy AI runtime context.

Key Shell Components

For details, see Application Shell: Routing, Navigation & Providers.

The Five Rooms Architecture

The core user experience is divided into five interactive "Rooms," each serving a specific stage of the cognitive capture and synthesis lifecycle.

Room-to-Code Mapping

The following diagram bridges the conceptual "Rooms" to their specific implementation files and the primary DI personas that inhabit them.

For details, see The Five Rooms.

Visual Design System & Atmosphere

The frontend utilizes a specialized "Atmosphere" system to provide visual identity to each room without code duplication. While most rooms use BabylonAtmosphere for 3D orb rendering client/src/pages/BlackboardRoomPage.tsx8 specific rooms like the Sanctuary use a custom layered atmosphere consisting of WillowTreeOverlay, FloatingEmbers, and FogOverlay client/src/pages/SanctuaryPage.tsx48-50

Billy UI Components

The "BillyLive" aesthetic is implemented through:

• ThinkingAnimation: A procedural text-based loading state client/src/pages/BlackboardRoomPage.tsx10
• BillyBabylon: A 3D WebGL orb representing the DI's current mood (idle, listening, processing, speaking) client/src/pages/AgentCouncilPage.tsx89-92
• GlassCard: A high-blur backdrop-filter component used for UI overlays client/src/pages/Home.tsx18

For details, see Billy UI Components & Visual Atmosphere.

Artifact Rendering Pipeline

When a user captures a "Bucket Drop" or synthesizes a document in the Creation Corner, it enters the client-side Rendering Engine. This pipeline classifies the content (Markdown, Mermaid diagrams, Video, etc.) and selects the appropriate renderer.

Rendering Workflow

1. Classification: artifactCardModel.ts determines the contentType (html, image, or text) client/src/pages/DynamicInnerWorldPage.tsx67-84
2. Dispatch: renderArtifact in renderingClient.ts routes the data to the correct UI component client/src/pages/CreationCornerPage.tsx48
3. Export: ArtifactExportViewer allows users to download artifacts in PNG, PDF, or HTML formats client/src/pages/CreationCornerPage.tsx47

For details, see Artifact Rendering Pipeline (Client).

Specialized Feature Modules

Beyond the core five rooms, the frontend hosts several specialized modules accessible via the TopNav or Home grid client/src/pages/Home.tsx24-34

For details, see Specialized Feature Pages & Modules.

Code-to-System Relationship

This diagram illustrates how core frontend hooks and libraries connect the UI to the backend and DI runtimes.

Sources: client/src/App.tsx1-120 client/src/pages/BlackboardRoomPage.tsx1-45 client/src/pages/SanctuaryPage.tsx1-40 client/src/pages/ExternalScaffoldPage.tsx1-60 client/src/pages/CreationCornerPage.tsx1-55 client/src/pages/DynamicInnerWorldPage.tsx1-100 client/src/hooks/useSEO.ts1-91 client/src/components/TopNav.tsx38-100 client/src/components/Scaffold.tsx7-55

Source MHT: Application Shell_ Routing, Navigation & Providers _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2.1-application-shell:-routing-navigation-and-providers \ Mermaid diagrams restored: 2

The GestaltView v2 application shell is a React 19 single-page application (SPA) built on Vite, utilizing wouter for lightweight routing and a centralized provider architecture to manage authentication, theme, and AI context. The shell implements a "Five Room" workflow, transitioning users from raw capture to structured artifacts through a highly stylized, neurodivergent-native interface.

Routing Architecture

The application uses wouter for routing, defined in client/src/App.tsx. The manifest includes over 80 routes, ranging from core room interfaces to specialized modules and administrative dashboards client/src/App.tsx23-105

Lazy Loading Strategy

To optimize initial bundle size, the application extensively uses React lazy and Suspense for almost all route components client/src/App.tsx23-105 This ensures that heavy dependencies (like BabylonJS for the Dynamic Inner World or Mermaid.js for diagrams) are only loaded when the user navigates to those specific surfaces.

Route Manifest Overview

Sources: client/src/App.tsx23-105 client/src/lib/billy-runtime-guide.ts3-9

Core Providers & Context

The application state is governed by a hierarchy of providers wrapped around the Switch component in App.tsx client/src/App.tsx189-230

• AuthProvider: Manages Supabase authentication state, user tiers (Free, Core, Pro, Enterprise), and founder-level permissions client/src/contexts/AuthContext.tsx
• ThemeProvider: Controls the visual "atmosphere" of the platform, facilitating transitions between high-contrast "BillyLive" modes and softer "Sanctuary" modes client/src/contexts/ThemeContext.tsx
• BillyProvider: Maintains the state of the Billy AI assistant, including the current "Billy Section" context, which allows Billy to provide location-aware guidance client/src/components/Billy.tsx

Data Flow: Routing and Navigation

The following diagram illustrates how the navigation components interact with the routing engine and feature flagging system.

Navigation & Feature Flagging Flow

Sources: client/src/App.tsx189-230 client/src/components/TopNav.tsx91-94 client/src/components/SubpageQuickNav.tsx9-131 client/src/config/featureFlags.ts

Navigation Systems

TopNav

The TopNav component provides a persistent global header. It dynamically filters navigation items based on the isFeatureEnabled utility client/src/components/TopNav.tsx91-94 It also includes a "Quick DI Launch" dropdown, allowing users to quickly jump into a Masterclass session with specific personas like "The Architect" or "The Weaver" client/src/components/TopNav.tsx67-74

SubpageQuickNav

SubpageQuickNav is a specialized navigation aid that appears on subpages to provide a "Back" context that isn't strictly hierarchical. It uses resolveSecondaryTarget to map the current location to a logical predecessor (e.g., /blackboard-room maps back to /sanctuary) client/src/components/SubpageQuickNav.tsx9-131

Feature Flagging

Feature flagging is centralized via isFeatureEnabled(flag: FeatureFlag). This allows the platform to hide unfinished rooms or restrict specific modules (like transcriptory or agentCouncil) to specific environments or user tiers client/src/config/featureFlags.ts client/src/components/TopNav.tsx38-51

Sources: client/src/components/TopNav.tsx38-51 client/src/components/TopNav.tsx67-74 client/src/components/SubpageQuickNav.tsx9-131

SEO & Prerendering

GestaltView implements a dual-layer SEO strategy to ensure visibility for crawlers despite being a heavy SPA.

useSEO Hook

The useSEO hook is used within page components to dynamically update document metadata (title, description, canonical URL) and inject a hidden h1 for accessibility and indexability client/src/hooks/useSEO.ts41-91 It includes a centralized PAGE_SEO record that maps route IDs to metadata client/src/hooks/useSEO.ts93-162

prerender.tsx

At build time, client/src/prerender.tsx is executed by the vite-prerender-plugin. This script renders a lightweight HTML shell for every major route. It intentionally excludes heavy libraries like BabylonJS or Framer Motion to remain compatible with Node.js environments client/src/prerender.tsx8-15

SEO Implementation Mapping

Sources: client/src/hooks/useSEO.ts41-91 client/src/prerender.tsx1-15 client/src/prerender.tsx29-156

Application Atmosphere & Home Surface

The Home.tsx component serves as the "Gateway" to the five rooms. It utilizes a high-fidelity visual stack:

• FloatingEmbers: A neon plasma particle system that provides depth and motion client/src/components/FloatingEmbers.tsx
• Hero Canvas: Renders a rolling fog and aurora effect using the 2D Canvas API client/src/components/home/Hero.tsx45-148
• Room Cards: A grid of GlassCard components that represent the primary workflow doorways, each with a specific neon glow color client/src/pages/Home.tsx24-34

Sources: client/src/pages/Home.tsx24-34 client/src/components/home/Hero.tsx45-148 client/src/components/FloatingEmbers.tsx27-36

Source MHT: The Five Rooms _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2.2-the-five-rooms \ Mermaid diagrams restored: 2

The GestaltView v2.0 architecture is organized into five interactive "Rooms." Each room represents a specific cognitive mode—Active, Structural, or Reflective—and serves as a stage in the capture lifecycle, transforming raw input into high-fidelity CodexArtifact entities.

The Capture Lifecycle

The transition from a raw thought to a permanent artifact follows a defined pipeline across the room architecture.

Sources: client/src/components/Scaffold.tsx:L7-L109, docs/ROOM_DEFINITIONS.md:L12-L23

1. Blackboard Room (Active / Contextual)

The Blackboard Room is the primary workspace for real-time collaboration between the user and a Digital Intelligence (DI), typically Billy. It is designed for "Mode 1" (Active) work, where clutter is minimized to focus on the current session.

Key Implementation

• File: client/src/pages/BlackboardRoomPage.tsx
• Routing: Uses routeBlackboardResponder to manage DI interactions client/src/pages/BlackboardRoomPage.tsx:L13.
• Capture Mechanism: Integrates UniversalCaptureBar for raw text and voice intake client/src/components/capture/UniversalCaptureBar.tsx:L23.

Session Recap Workflow

The room features a SessionRecapGenerator that synthesizes the entire session history into a self-contained HTML artifact.

• Function: appendBlackboardRecapToInnerWorld client/src/lib/blackboardRecapArtifacts.ts.
• Output: A RecapArtifact that is automatically routed to the Dynamic Inner World docs/ROOM_DEFINITIONS.md:L68-L71.

Sources: client/src/pages/BlackboardRoomPage.tsx:L48-L91, docs/ROOM_DEFINITIONS.md:L46-L93

2. External Scaffold (Accumulated / Structural)

The External Scaffold represents "Mode 2" (Accumulated). It provides a complete cumulative visual layer of all CaptureOrb entities, organized by category and causal connections.

Data Flow: Capture to Scaffold

1. Raw input is wrapped in a CaptureOrb client/src/components/Scaffold.tsx:L94-L109.
2. Orbs are placed in the scaffoldQueue (pending status) client/src/components/Scaffold.tsx:L198.
3. Upon approval via approveScaffoldOrbThroughPipeline, they become ScaffoldArtifacts with 3D coordinates client/src/lib/profilePipeline/scaffoldRouting.ts:L53.

Visual Mapping

The Scaffold uses a "Galaxy" layout where artifacts are projected based on resonance and time.

• Projection Logic: projectArtifact() calculates left, top, and displaySize based on the ScaffoldPosition (x, y, z) client/src/pages/ExternalScaffoldPage.tsx:L96-L104.

Sources: client/src/pages/ExternalScaffoldPage.tsx:L126-L208, client/src/components/Scaffold.tsx:L147-L161

3. Creation Corner (Artifact Forging)

The Creation Corner is the "Forge" where raw captures are synthesized into high-order artifacts. It interfaces with the Gen Engine to produce structured outputs.

Synthesis Process

Users select CaptureBlueprints (collections of orbs) and "materialize" them into specific ArtifactTypes such as markdown, mind_map, or code.

Technical Pipeline

1. Selection: readBlueprints() retrieves stored collections client/src/pages/CreationCornerPage.tsx:L25.
2. Orchestration: requestOrchestrationDecision() determines the best DI for the task client/src/pages/CreationCornerPage.tsx:L21.
3. Synthesis: synthesizeArtifact() (aliased from createArtifact) calls the /api/codex/forge endpoint client/src/pages/CreationCornerPage.tsx:L20.
4. Result: Produces a CodexArtifact containing HTML, Markdown, or JSON exports shared/codex/contracts.ts.

Sources: client/src/pages/CreationCornerPage.tsx:L149-L180, docs/ROOM_DEFINITIONS.md:L123-L150

4. Dynamic Inner World (Reflective / Museum)

The Dynamic Inner World (Museum of You) is "Mode 3" (Reflective). It displays synthesized InnerWorldArtifactRecord entities as high-fidelity exhibits.

The World Renderer

The room utilizes a specialized spatial renderer to organize artifacts across six surfaces: forward, back, left, right, ceiling, and floor.

Entity Mapping: Code to UI

The following diagram illustrates how the InnerWorldArtifactRecord data structure is transformed into the visual "Exhibit" components.

Diagram: Artifact to Museum Exhibit Mapping

Sources: client/src/lib/innerWorldFiles.ts:L35-L50, client/src/components/inner-world/InnerWorldRoom.tsx:L16-L56, api/inner-world/artifacts.ts:L87-L108

5. Sanctuary (Restoration / Privacy)

The Sanctuary is a private, low-intensity room for journaling and unclassified fragments. Unlike other rooms, it does not use the standard BabylonAtmosphere.

Unique Characteristics

• Visual Identity: Implements WillowTreeOverlay, FloatingEmbers, and FogOverlay for a distinct aesthetic client/src/pages/SanctuaryPage.tsx:L48-L50.
• Privacy: Designed for "Mode 1" writing that is not yet ready for the Scaffold docs/ROOM_DEFINITIONS.md:L154-L158.
• Integrations: Hosts the MusicalDNAHub for personal musical identity tracking client/src/pages/SanctuaryPage.tsx:L23.

Sources: client/src/pages/SanctuaryPage.tsx:L12-L42, docs/ROOM_DEFINITIONS.md:L152-L178

Room Interaction and Data Flow

The following diagram maps the transition of data through the "Five Rooms" pipeline, specifically highlighting the functions and API handlers involved.

Diagram: The Five Rooms Data Pipeline

Sources: client/src/lib/captureRouting.ts, client/src/lib/profilePipeline/scaffoldRouting.ts:L53, client/src/pages/CreationCornerPage.tsx:L43, api/_lib/inner-world.ts:L7-L9

Source MHT: Billy UI Components & Visual Atmosphere _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2.3-billy-ui-components-and-visual-atmosphere \ Mermaid diagrams restored: 2

This page details the user interface components and visual design system that define the "Billy" experience. Billy is the primary Digital Intelligence (DI) interface of GestaltView, characterized by a "BillyLive" aesthetic—a high-contrast, teal-on-black, terminal-inspired environment utilizing JetBrains Mono and CRT-style scanlines.

1. Core Chat Interfaces

The platform provides two primary ways to interact with Billy: a persistent sidebar/panel for general use and a dedicated full-screen "Live" experience.

Billy.tsx (The Application Shell Interface)

The Billy.tsx file defines the standard interface integrated into the platform's layout. It includes:

• BillyOrb: A floating presence indicator in the bottom-right corner that renders the BillyBabylon avatar client/src/components/Billy.tsx5
• BillyPanel: A synthesis panel that slides in from the right to facilitate chat, context weaving, and retrieval-grounded synthesis client/src/components/Billy.tsx6
• BillyProvider: A React context provider that manages state for isLoading, isListening, and the currentSection observer client/src/components/Billy.tsx8-17

BillyLive.tsx (The Immersive Interface)

BillyLive.tsx provides a standalone, full-screen environment. It emphasizes "Founder Continuity" and persistent mode switching client/src/components/BillyLive.tsx4-6

• Modes: Users can switch between THINK (Synthesis: context weave, retrieval grounding) and VIBE (Chat: conversational, no forced frameworks) client/src/components/BillyLive.tsx60-69
• Aesthetic: Implements a "March 2026" update featuring a scanlines overlay, sweep-line animations, and terminal-green/teal color palettes client/src/components/BillyLive.tsx88-101

Component Relationship Diagram

This diagram shows how the UI components connect to the underlying DI logic.

Sources: client/src/components/Billy.tsx19-85 client/src/components/BillyLive.tsx13-112 client/src/components/BillyLive.tsx22-30

2. Visual Atmosphere & Babylon.js Integration

The "Atmosphere" of GestaltView is a blend of brutalist digital aesthetics and organic, ethereal overlays.

BillyBabylon (The Orb)

The "heart" of the interface is a 3D avatar rendered using Babylon.js. It responds to Billy's internal state via a mood prop:

• idle: Standard floating animation client/src/components/BillyLive.tsx85
• listening: Responsive movement during voice input client/src/components/BillyLive.tsx86
• processing: A "glitch" animation used when the LLM is generating a response client/src/components/BillyLive.tsx87

Sanctuary & Environmental Overlays

Beyond the chat interface, specific rooms utilize specialized visual components:

• SanctuaryWillowBabylon: A fixed overlay for the Sanctuary room. it combines a WillowTreeOverlay with fireflies and fog effects to create a restorative atmosphere client/src/components/SanctuaryWillowBabylon.tsx11-34
• HeroCanvas: Provides the high-performance background for the landing and "hero" sections of the site.
• AuroraBackground: Used in pages like the MuseumPage to provide a subtle, shifting light effect client/src/pages/MuseumPage.tsx81

Atmosphere Data Flow

Sources: client/src/components/SanctuaryWillowBabylon.tsx1-34 client/src/components/BillyLive.tsx71-112 client/src/components/NeuralThinkingIndicator.tsx4-139

3. Cognitive State Visualizations

GestaltView uses specific animations to represent the "thinking" process of the Digital Intelligence.

ThinkingAnimation.tsx

This component replaces standard loading spinners with narrative "thinking messages."

• Logic: It shuffles through an array of thinkingMessages (e.g., "Retrieving context shards...", "Consulting the Manifest Index") client/src/lib/thinkingMessages.ts6-17
• Implementation: Uses a CSS-based pulse and spin animation on a custom SVG icon client/src/components/thinking/ThinkingAnimation.css30-60

NeuralThinkingIndicator.tsx

A more advanced version of the thinking state that adapts based on which DI profile is active (e.g., Billy, The Architect, The Curator).

• DI Profiles: Each profile has a unique sigil, color, and set of phrases client/src/components/NeuralThinkingIndicator.tsx4-139
• NeuralSigil: A kinetic component that spins and pulses in the DI's specific color client/src/components/NeuralThinkingIndicator.tsx147-181

DI Profile Mapping

Sources: client/src/components/thinking/ThinkingAnimation.tsx1-160 client/src/components/NeuralThinkingIndicator.tsx4-139 client/src/lib/thinkingMessages.ts1-17

4. The BillyLive Aesthetic (CSS & Theme)

The "BillyLive" aesthetic is defined by a specific set of constants and global styles used to ensure visual continuity across different chat components.

Theme Constants (T)

The system uses a unified color palette for terminal-style elements:

• teal: #00D4FF (Primary interaction)
• dim: #006B7F (Subtle borders/placeholders)
• dark: #0A0F14 (Main background)
• ok: rgba(16, 185, 129, .7) (Ready status) client/src/components/BillyLive.tsx36-46

Key Visual Effects

1. Scanlines: A repeating linear gradient that mimics CRT monitor lines client/src/components/BillyLive.tsx88-91
2. Sweep Line: A horizontal "radar" line that moves vertically across the screen every 12 seconds client/src/components/BillyLive.tsx92-96
3. Glitch Animation: Rapid transformation/translation used during "processing" states client/src/components/BillyLive.tsx76-80

Component Architecture: Billy Interface Logic

Sources: client/src/components/Billy.tsx67-85 client/src/components/BillyLive.tsx22-30 client/src/components/BillyLive.tsx128-143

Source MHT: Artifact Rendering Pipeline (Client) _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2.4-artifact-rendering-pipeline-(client) \ Mermaid diagrams restored: 2

The Artifact Rendering Pipeline is a sophisticated client-side engine responsible for transforming raw data structures (CodexArtifacts, CaptureAttachments, and Synthesis results) into rich, interactive visual representations. It operates as a multimodal dispatch system that classifies content and routes it to specialized renderers while maintaining the platform's "Neural Aurora" aesthetic.

Pipeline Overview

The rendering process follows a strict lifecycle: Classification → Dispatch → Rendering → Export.

1. Classification: The system analyzes the artifact's metadata and content using artifactCardModel.ts to determine the most appropriate visual mode.
2. Dispatch: dispatch.ts routes the artifact to a specific React component based on the classification.
3. Rendering: Specialized renderers (Markdown, Mermaid, MindMap, etc.) process the content.
4. Export: The ArtifactExportViewer provides tools for converting the live DOM into portable formats like PNG or PDF.

System Data Flow

The following diagram illustrates the flow from raw data to a rendered UI component.

Artifact Classification and Dispatch Flow

Sources: client/src/lib/rendering/RenderingEngine.tsx:1-20, client/src/lib/rendering/dispatch.ts:1-30, client/src/lib/rendering/multimodal/artifactCardModel.ts:1-50

1. Classification & Artifact Card Model

Before rendering, the system must decide how to treat the data. The buildArtifactCardModel function in artifactCardModel.ts acts as the primary heuristic engine.

Key Classification Logic

The system identifies content types through a mix of MIME types, file extensions, and regex patterns:

• Markdown: Identified by .md extensions, text/markdown MIME, or the presence of headers (#) and lists client/src/components/ArtifactPreview.tsx44-56
• Code: Identified by programming language extensions (.ts, .js, .json) or markdown code blocks client/src/components/ArtifactPreview.tsx58-62
• HTML/Recap: Detected via <!doctype html> or <html> tags, or specific artifact types like recap client/src/components/ArtifactPreview.tsx70-81

Sources: client/src/lib/rendering/multimodal/artifactCardModel.ts:10-100, client/src/components/ArtifactPreview.tsx:44-81

2. The Rendering Engine

The RenderingEngine is the top-level React component that orchestrates the display of any artifact. It uses dispatch.ts to select a renderer from the registry.ts.

Core Renderers

Mermaid Integration

The MermaidDiagram component handles the lifecycle of Mermaid rendering, including initialization and dynamic re-renders when the content changes client/src/lib/rendering/diagram/MermaidDiagram.tsx1-40 It utilizes a dedicated mermaidLoader.ts to ensure the library is loaded only when needed.

Sources: client/src/lib/rendering/registry.ts:1-25, client/src/lib/rendering/diagram/MermaidDiagram.tsx:1-40, client/src/lib/rendering/renderers/HtmlArtifactRenderer.tsx:1-30

3. Export & DOM Capture

GestaltView provides a high-fidelity export system that allows users to capture rendered artifacts as images.

domCapture Implementation

The domCapture.ts utility is the core of this system. It performs the following steps:

1. Cloning: Deep clones the target DOM node.
2. Styles Inlining: Computes and inlines all CSS styles to ensure the export looks identical to the live UI.
3. Canvas Conversion: Uses a canvas-based approach to generate a PNG blob.
4. Download: Triggers the browser download via downloadCapturedDomNode client/src/lib/rendering/capture/domCapture.ts50-120

ArtifactExportViewer

This component provides the UI for the export process, including format selection (PNG, PDF, JSON) and a preview of the export boundaries client/src/lib/rendering/ArtifactExportViewer.tsx10-60

Sources: client/src/lib/rendering/capture/domCapture.ts:1-150, client/src/lib/rendering/ArtifactExportViewer.tsx:1-100

4. Component Architecture (Preview vs. Expand)

The UI utilizes two primary patterns for artifact interaction:

ArtifactPreview

A non-interactive or semi-interactive component used in galleries and chat feeds. It uses artifactBody to determine if it should show a file icon, an image preview, or a snippet of text client/src/components/ArtifactPreview.tsx83-173

ArtifactExpandView

A full-screen or modal-based view that enables the full RenderingEngine. This view provides:

• Full interactivity (e.g., zooming in Mind Maps).
• Access to the ArtifactExportBar.
• Metadata inspection.

Client Rendering Class Diagram

Sources: client/src/lib/rendering/RenderingEngine.tsx:5-15, client/src/lib/rendering/dispatch.ts:5-15, client/src/lib/rendering/capture/domCapture.ts:7-15

5. Summary of Key Files

• client/src/lib/rendering/RenderingEngine.tsx: The main entry point for the rendering subsystem client/src/lib/rendering/RenderingEngine.tsx1-50
• client/src/lib/rendering/dispatch.ts: The routing logic for renderers client/src/lib/rendering/dispatch.ts1-40
• client/src/lib/rendering/multimodal/artifactCardModel.ts: Heuristics for artifact classification client/src/lib/rendering/multimodal/artifactCardModel.ts1-120
• client/src/lib/rendering/capture/domCapture.ts: The engine for PNG/PDF generation from the DOM client/src/lib/rendering/capture/domCapture.ts1-200
• client/src/components/ArtifactPreview.tsx: The primary UI component for artifact thumbnails and snippets client/src/components/ArtifactPreview.tsx1-250

Sources: client/src/lib/rendering/index.ts:1-10, client/src/lib/rendering/types.ts:1-50

Source MHT: Specialized Feature Pages & Modules _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/2.5-specialized-feature-pages-and-modules \ Mermaid diagrams restored: 2

This section documents the specialized platform modules within GestaltView v2.0. These modules extend the core "Five Rooms" architecture by providing focused interfaces for identity management, progress tracking, creative synthesis, and administrative governance. Each module integrates with the Digital Intelligence (DI) runtime and utilizes shared persistence layers in Supabase.

Profile & Identity Management

The ProfilePage serves as the primary interface for managing user preferences and "Portrait" generation. It bridges local browser state with server-side persistence to maintain continuity across sessions.

Implementation & Data Flow

• Preferences Sync: Preferences are initially read from localStorage using readLocalPreferences client/src/pages/ProfilePage.tsx63-84 and then synchronized with the server via appFetchJson("/api/profile/preferences") client/src/pages/ProfilePage.tsx178-192
• Embodiment Assignment: Users can select their active DI embodiment from ASSIGNABLE_PROFILES, which filters out founder-only profiles client/src/pages/ProfilePage.tsx59-61
• Portrait Inference: The page utilizes the usePortrait hook client/src/pages/ProfilePage.tsx167 to trigger and display the results of the "Profile Portrait" pipeline, which analyzes signals like Bucket Drops and session transcripts to infer the user's personality dimensions.

Identity Code Mapping

Sources: client/src/pages/ProfilePage.tsx1-200 api/profile/preferences.ts

Musical DNA

The Musical DNA module is a specialized biofeedback and creative synthesis environment. It maps musical attributes (BPM, key, archetypes) to the user's nervous system patterns.

Technical Architecture

• Spotify Integration: Utilizes beginSpotifyAuthFlow and fetchSpotifyPlaylistTracks client/src/pages/MusicalDNAPage.tsx26-33 to ingest user listening history.
• Ambient Analysis: The musicalDnaAmbient.ts library builds analysis artifacts from journals and file uploads client/src/pages/MusicalDNAPage.tsx36-41
• Somatic Modes: Implements three playback modes—bilateral, trilateral, and quadlateral client/src/pages/MusicalDNAPage.tsx51-88—which affect the visualizer and entrainment phase.
• Billy Bridge: The useBillyExhibitBridge hook provides the DI with real-time state awareness of the user's biofeedback and current track client/src/pages/MusicalDNAPage.tsx124-129

Musical DNA Logic Flow

Sources: client/src/pages/MusicalDNAPage.tsx1-130 client/src/lib/musicalDnaTracks.ts client/src/lib/musicalDnaAmbient.ts

Masterclass & Progress Tracking

The Masterclass module provides a structured curriculum for interacting with the various DI embodiments. It categorizes the EMBODIMENT_REGISTRY into five domains: Relational, Analytical, Creative, Operational, and Ethical client/src/pages/MasterclassPage.tsx26-54

Core Components

• Curriculum Order: Defined in CURRICULUM_ORDER client/src/pages/MasterclassPage.tsx95-101 starting with Relational Intelligence (Billy).
• Briefing Modal: A pre-launch interface that displays a DI's "Foundational Truth" and "Voice Tone" client/src/pages/MasterclassPage.tsx111-180 before a session begins.
• Persistence: Progress is tracked via the useMasterclassProgress hook client/src/pages/MasterclassPage.tsx17 which interfaces with the masterclass_progress_tracking Supabase table.

Sources: client/src/pages/MasterclassPage.tsx1-120 client/src/features/masterclass/MasterclassProfileCard.tsx1-96

Transcriptory

The Transcriptory acts as a central repository for voice notes, transcripts, and raw source captures. It supports both local-first capture and Supabase persistence.

Implementation Details

• Session Management: Captures are grouped into TranscriptorySession objects client/src/lib/transcriptory.ts29-40
• Audio Processing: Integrates with AssemblyAI via transcribeTranscriptoryAudio client/src/pages/TranscriptoryPage.tsx173 for speech-to-text conversion.
• Handoff Mechanism: Allows "handing off" transcripts to the Blackboard Room or Creation Corner using writeTranscriptoryHandoff client/src/lib/transcriptory.ts99-111 This uses sessionStorage keys like gestaltview.transcriptory.blackboardHandoff.v1.

Transcriptory State Diagram

Sources: client/src/pages/TranscriptoryPage.tsx1-200 client/src/lib/transcriptory.ts1-175

Dashboard & Admin Tools

The DashboardPage provides a high-level overview of system health, user tiers, and administrative controls.

Key Modules

• Founder Context: Specialized controls for the "Founder" (Keith Soyka) to manage PLK snapshots and session threads client/src/pages/DashboardPage.tsx73-82
• Billy Health: Monitors the health of LLM providers (Groq, OpenAI, etc.) and the voice stack (ElevenLabs, LiveKit) client/src/pages/DashboardPage.tsx90-110
• Orchestration Analytics: Displays real-time metrics on DI routing and tribunal decisions client/src/pages/DashboardPage.tsx46
• Memory Management: Allows manual CRUD operations on DashboardMemoryEntry items, which populate the DI's long-term memory client/src/pages/DashboardPage.tsx132-150

Sources: client/src/pages/DashboardPage.tsx1-250 client/src/lib/dashboardOverview.ts

Sandbox & Token Tester

The SandboxPage is a developer-focused utility for testing "Neural Aurora" design tokens and live-previewing HTML/CSS artifacts.

• Neural Aurora Tokens: Defined in NA_TOKENS client/src/pages/SandboxPage.tsx4-20 covering colors like obsidian, cyan, and violet.
• Live Preview: Uses a sandboxed iframe with srcDoc client/src/pages/SandboxPage.tsx103-116 to render user-provided HTML with injected CRT_CSS scanlines client/src/pages/SandboxPage.tsx23-39

Sources: client/src/pages/SandboxPage.tsx1-249

GATE Package Builder

The GATE (Gestalt Intelligence Training & Embodiment) system handles the commercial packaging of DI frameworks.

• Packaging Panel: The PackagingGatePanel client/src/pages/DashboardPage.tsx45 allows administrators to define package tiers (Solo Spark, Studio, Growth, Enterprise).
• Order Status: Tracks the lifecycle of a GATE package from draft to redeem via Supabase tables gate_orders and gate_build_jobs.

Sources: client/src/pages/DashboardPage.tsx45-48 Wiki Section 9.1

Source MHT: Billy & Digital Intelligence (DI) Runtime _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3-billy-and-digital-intelligence-(di)-runtime \ Mermaid diagrams restored: 1

The Billy & Digital Intelligence (DI) Runtime is the core cognitive engine of GestaltView. It orchestrates interactions between the user and a diverse roster of specialized Digital Intelligences, anchored by Billy, the primary DI. The system is designed around the principle of consciousness-serving AI, ensuring continuity, dignity, and high-fidelity retrieval of user context across the platform's five rooms README.md27-33

This runtime is not a simple chatbot wrapper; it is a multi-layered pipeline that handles semantic memory retrieval, multi-model routing, and agent orchestration governed by the Ten Constitutional Invariants README.md51-75

The DI Ecosystem Overview

The runtime manages over 20 named Digital Intelligences, each with a unique profile defined in the EMBODIMENT_REGISTRY client/src/components/TopNav.tsx25 These personas, such as the Art Teacher, Curator, and The Architect, provide specialized support across different platform modules client/src/components/TopNav.tsx68-73

System Architecture: Natural Language to Code Entities

The following diagram bridges the high-level conceptual spaces of user interaction (Natural Language Space) with the underlying architectural components (Code Entity Space).

DI Runtime Architecture & Entity Mapping

Sources: client/src/lib/billyApi.ts api/billy.ts api/_lib/billyMemoryPipeline.ts client/src/pages/AgentCouncilPage.tsx115-135 README.md99-105

3.1 Billy Request Lifecycle & LLM Router

The Billy request pipeline is a sophisticated RAG (Retrieval-Augmented Generation) flow. When a user sends a message, the system performs a bootstrap process that includes embedding generation and semantic retrieval from specialized tables (knowledge_fragments, skill_fragments, and memory_entries). It utilizes Reciprocal Rank Fusion (RRF) to prioritize the most relevant context before passing the "envelope" to the llmRouter.ts. The router manages a failover cascade across multiple providers including Ollama, Groq, HuggingFace, OpenRouter, Gemini, Anthropic, and OpenAI.

For details, see Billy Request Lifecycle & LLM Router.

Sources: README.md99-105 api/billy.ts api/_lib/billyMemoryPipeline.ts

3.2 Agent Council (Tribunal) & Multi-Agent Orchestration

The Tribunal (or Agent Council) is a specialized environment for multi-agent collaboration. It supports three distinct interaction modes: SESSION, DEBATE, and ROUNDTABLE client/src/pages/AgentCouncilPage.tsx5-9 The system uses a roundtableQueue and mentionParser to allow agents to address each other by name, creating a collaborative deliberation process that prevents the "flattening" of user complexity.

For details, see Agent Council (Tribunal) & Multi-Agent Orchestration.

Sources: client/src/pages/AgentCouncilPage.tsx115-135 shared/roundtable/mentionParser.ts

3.3 PLK (Private Language Key) & Prompt Shaping

The Private Language Key (PLK) is the mechanism for maintaining linguistic continuity. It ensures the DI uses the user's exact vocabulary and conceptual frameworks README.md60 The plk.ts module shapes prompts to maintain a "Resonance Loop," grounded by the billy-runtime-guide.ts and the BILLY_WORKFLOW_SPINE, ensuring that every response aligns with the user's unique cognitive signature.

For details, see PLK (Private Language Key) & Prompt Shaping.

Sources: client/src/lib/billy-runtime-guide.ts client/src/pages/ResonanceLoopPage.tsx

3.4 GPT Actions & External AI Integrations

Billy interacts with the physical and digital world through GPT Actions. This subsystem is defined by a comprehensive OpenAPI specification and handled via actionsHandler.ts. It allows the DI to perform tasks such as searching the web via Perplexity Computer Tools or interacting with external APIs, all while maintaining the platform's privacy and governance standards.

For details, see GPT Actions & External AI Integrations.

Sources: tools/index.ts api/billy.ts

3.5 Voice Pipeline (Billy Voice)

The Billy Voice system provides a low-latency, multi-modal interface. Built on a Python runtime, it integrates LiveKit for room management, faster-whisper for Speech-to-Text (STT), and CosyVoice for Text-to-Speech (TTS). A "Style Planner" ensures that Billy's vocal delivery matches the emotional tone and urgency of the interaction.

For details, see Voice Pipeline (Billy Voice).

Sources: billy_voice/ (directory), api/voice/billy.ts

Data Interaction Model

The following table details how the DI Runtime interacts with core system entities during a standard execution cycle.

Sources: README.md51-140 client/src/pages/AgentCouncilPage.tsx api/_lib/billyMemoryPipeline.ts

Source MHT: Billy Request Lifecycle & LLM Router _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3.1-billy-request-lifecycle-and-llm-router \ Mermaid diagrams restored: 2

The Billy Request Lifecycle is the core cognitive pipeline of GestaltView. It manages the transition from a user's natural language input to a multi-stage retrieval process, grounding the response in the platform's corpus and the user's persistent memory before dispatching the request through a prioritized multi-LLM routing cascade.

1. Request Pipeline & Bootstrap

The lifecycle begins either via a bootstrap event or a standard user message. The api/billy.ts handler serves as the entry point for both api/billy.ts1-15

Bootstrap Mechanism

When a session starts, the client calls bootstrapBillySession client/src/lib/billyApi.ts192-196 If the bootstrap flag is true, Billy skips retrieval and generates a warm greeting based on the BOOTSTRAP_PROMPT api/billy.ts67-71 This process uses the FounderContext to maintain continuity if the user is recognized as the platform founder api/billy.ts153-168

Data Flow: Entry to Embedding

For standard queries, the pipeline follows these steps:

1. Auth & Correlation: Validates the user via getAuthUser and assigns a requestId for tracing api/billy.ts17-117
2. Intent Classification: Injects analysis from SymbioCoder (intent/emotion) and VibeCoder (vibe alignment) to shape the prompt api/billy.ts12-13
3. Embedding Generation: The query is converted into a vector using embedTextForRetrieval. The system supports multiple backends including Gemini, Ollama, and HuggingFace api/_lib/embeddings.ts

Diagram: Request Ingestion & Grounding

This diagram bridges the Natural Language Space (User Input) to the Code Entity Space (Retrieval & Grounding).

Sources: api/billy.ts15-56 api/_lib/embeddings.ts api/_lib/memory.ts23

2. Semantic Retrieval & RRF

Billy utilizes a hybrid retrieval strategy to ensure responses are grounded in both static knowledge and living memory.

Retrieval Streams

The system queries three distinct streams in parallel:

• Knowledge Fragments: Core platform doctrine and truth claims api/billy.ts25-26
• Skill Fragments: Operational capabilities and tool definitions api/billy.ts27-28
• Memory Entries: User-specific history and persistent context api/billy.ts23

Reciprocal Rank Fusion (RRF)

To reconcile results from semantic (vector) search and keyword (text) search, Billy implements RRF. This ensures that a fragment appearing high in both search types is prioritized over fragments that only score well in one api/billy.ts7-9 The system limits context to a maximum of 14 chunks to manage LLM context windows, with specific caps for skills and memories api/billy.ts58-65

Two-Pass Gravity Protocol

Before the context is finalized, the runTwoPassGravityProtocol evaluates the "load-bearing claims" within the retrieved chunks to ensure cognitive integrity api/billy.ts48-52

Sources: api/billy.ts58-65 api/billy.ts25-32 api/billy.ts48-52

3. The LLM Router Cascade

The llmRouter.ts manages a sophisticated failover cascade. It attempts to fulfill the request using the most efficient available provider, falling back to others if errors or timeouts occur.

The Cascade Order

The router follows a specific priority hierarchy api/_lib/llmRouter.ts:

1. Ollama: Local execution (if available).
2. Groq: High-speed inference.
3. HuggingFace: Open-source model hosting.
4. OpenRouter: Aggregator for various models.
5. Gemini: Google's frontier models.
6. Anthropic: Claude series.
7. OpenAI: GPT series.

Envelope Wrapping

Every response from the router is wrapped in a standard envelope api/_lib/response.js This envelope includes the generated text, the provider that fulfilled the request, and a metadata object containing the retrievalMode, latency_ms, and founderSessionActive status client/src/lib/billyApi.ts17-61

Diagram: LLM Router Cascade

This diagram maps the Routing Logic to the specific Provider Implementation in the code.

Sources: api/_lib/llmRouter.ts api/_lib/response.js client/src/lib/billyApi.ts84-94

4. Continuity & Keep-Alive

To maintain system readiness and user context, GestaltView employs two critical background mechanisms.

Keep-Alive Mechanism

The api/keep-alive.ts endpoint is a lightweight cron handler that runs every 5 minutes api/keep-alive.ts234-238 It performs a minimal REST read on the documents table to prevent Supabase from entering a dormant state api/keep-alive.ts93-101 It tracks latency and reports the health of the DB connection api/keep-alive.ts203-216

Client-Side Recovery

If the primary API call fails, the client uses readLastGoodBillyContinuity to load session metadata from localStorage client/src/lib/billyApi.ts122-135 This allows Billy to function in a "degraded" mode, using the local-continuity-cache provider until connectivity is restored client/src/lib/billyApi.ts216-221

Sources: api/keep-alive.ts1-15 api/keep-alive.ts93-120 client/src/lib/billyApi.ts96-153 client/src/lib/billyApi.ts215-228

Source MHT: Agent Council (Tribunal) & Multi-Agent Orchestration _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3.2-agent-council-(tribunal)-and-multi-agent-orchestration \ Mermaid diagrams restored: 2

The Agent Council (Tribunal) is the primary multi-agent orchestration surface within GestaltView. It facilitates structured dialogue between different Digital Intelligence (DI) personas, allowing them to collaborate, debate, or provide sequenced feedback on user prompts. This system moves beyond single-agent interaction into a governed "roundtable" environment where specialized agents coordinate care, scaffolding, and legacy preservation client/src/prerender.tsx114-118

Tribunal Modes & Session Lifecycle

The Tribunal operates in three distinct interaction modes, defined in the AgentCouncilPage component client/src/pages/AgentCouncilPage.tsx115 These modes determine how messages flow between the user and the participating agents.

Data Flow: Natural Language to Code Entity

The following diagram illustrates how a user request moves from the UI into the orchestration layer and back to the Council view.

Tribunal Request Pipeline

Sources: client/src/pages/AgentCouncilPage.tsx31-45 client/src/pages/AgentCouncilPage.tsx124-135

Core Implementation Details

Mention Parsing & Addressing

In ROUNDTABLE mode, agents must be able to recognize when they are being addressed. The system uses extractTribunalMentions to scan message content for agent names or slugs client/src/pages/AgentCouncilPage.tsx45 This allows the orchestration layer to manage a roundtableQueue and determine which agent should respond next based on addressedTo metadata client/src/pages/AgentCouncilPage.tsx132

Stance Inference

The system utilizes inferDefaultTribunalStance (referenced via TribunalStance type) to establish an agent's initial position or "vibe" before a session begins client/src/pages/AgentCouncilPage.tsx44 This ensures that agents like "The Guardian" or "The Architect" maintain their constitutional roles during the debate.

Resilience & Timeouts

Because multi-agent sessions involve multiple LLM calls, the system implements a robust retry mechanism:

• useTribunalRetry: A custom hook that manages retries for failed agent responses client/src/pages/AgentCouncilPage.tsx42
• TRIBUNAL_RETRY_OPTIONS: Configured for a maximum of 2 retries with exponential backoff (1000ms, 2000ms) client/src/pages/AgentCouncilPage.tsx71
• withTimeout / callWithRetry: Used within the underlying API calls to prevent a single hanging agent from blocking the entire council session.

Multi-Agent Orchestration Layer

The orchestration layer coordinates between the Tribunal UI and the DI Runtime. It relies on three primary classifiers to route intent and maintain state.

1. Intent Classifier

Determines if the user is seeking a direct answer, a debate, or an artifact synthesis. If the intent is classified as requiring multiple perspectives, the skillRouter may suggest opening a Tribunal session shared/orchestration/skillRouter.ts

2. State Classifier

Tracks the "mood" and "readiness" of the agents. In the UI, this is reflected via AgentMood (idle, listening, processing, speaking) client/src/pages/AgentCouncilPage.tsx116

• Processing: Triggered during active LLM generation, often accompanied by the ac-glitch animation client/src/pages/AgentCouncilPage.tsx91
• Speaking: Triggered when the response is being streamed to the BillyMarkdown component client/src/pages/AgentCouncilPage.tsx33

3. Skill Router

Maps the user's request to specific agent capabilities. For example, if a request involves structural mapping, the skillRouter prioritizes "The Architect" within the council participant list shared/orchestration/skillRouter.ts

Orchestration Logic Mapping

Sources: client/src/pages/AgentCouncilPage.tsx34-35 shared/embodiment/types.ts220-228

Technical Configuration

Participant Limits

The number of agents that can participate in a single Tribunal session is governed by user entitlements:

• Limit: Defined by ADVANCED_TRIBUNAL_PARTICIPANT_LIMIT client/src/pages/AgentCouncilPage.tsx37
• Access: Controlled via canUseAdvancedTribunal, which checks the user's tier (e.g., Core, Pro, Enterprise) client/src/pages/AgentCouncilPage.tsx39-40

Visual Signature

Each agent in the council is represented by a BillyBabylon orb client/src/pages/AgentCouncilPage.tsx53 The visual state of these orbs is tied to the EmbodimentUIPresence and EmbodimentVisualSignature interfaces:

• orbColor: Defines the primary glow color for the agent shared/embodiment/types.ts175
• motionCadence: Controls the pulse style (e.g., slow-pulse, electric-flicker) shared/embodiment/types.ts209-217
• ac-scanlines: A CSS-based overlay that provides the "BillyLive" aesthetic client/src/pages/AgentCouncilPage.tsx94-97

Sources: client/src/pages/AgentCouncilPage.tsx17-53 shared/embodiment/types.ts174-218 client/src/prerender.tsx114-125

Source MHT: PLK (Private Language Key) & Prompt Shaping _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3.3-plk-(private-language-key)-and-prompt-shaping \ Mermaid diagrams restored: 2

The Private Language Key (PLK) and Prompt Shaping system represent the core of GestaltView’s "Consciousness-Serving" architecture. Unlike standard AI systems that prioritize linguistic normalization (paraphrasing user input into "clean" tokens), GestaltView enforces User Invariant U-2: Preserve Whole Language README.md60 The PLK system ensures that the Digital Intelligence (DI), primarily Billy, operates within the user's specific linguistic patterns, metaphors, and cognitive frameworks without flattening them.

The PLK (Private Language Key) System

The PLK is a dynamic linguistic anchor that shapes every interaction between the user and the DI. It is designed to maintain continuity across sessions by recognizing and reflecting the user's exact vocabulary and conceptual "shorthand."

Core Principles

• Linguistic Continuity: The system identifies recurring patterns in user input and integrates them into the prompt context to ensure the AI speaks "with" the user, not "at" them.
• Resonance Loop: A feedback mechanism where the DI validates its understanding of the user's PLK, deepening alignment over time client/src/App.tsx25-27
• Anti-Normalization: Explicitly forbids the LLM from paraphrasing or "cleaning up" the user's raw thinking README.md60

Prompt Shaping Data Flow

The shaping process occurs in the shared/llm/ layer (and associated runtime guides), where raw user input is wrapped with structural metadata and constitutional constraints before reaching the llmRouter.ts api/_lib/llmRouter.ts

System Prompt Architecture

The system relies on three primary pillars of shaping:

1. billy-system-prompt.ts: The foundational identity and safety layer client/src/lib/billy-system-prompt.ts
2. billy-runtime-guide.ts: Real-time operational instructions for the DI client/src/lib/billy-runtime-guide.ts
3. BILLY_WORKFLOW_SPINE: The structural sequence for processing complex requests.

Natural Language to Code Entity Mapping (PLK Shaping)

The following diagram bridges the conceptual "Natural Language Space" of user intent to the "Code Entity Space" where prompt shaping is executed.

Sources: README.md27-33 client/src/lib/billy-system-prompt.ts client/src/lib/billy-runtime-guide.ts api/_lib/llmRouter.ts

The BILLY_WORKFLOW_SPINE

The BILLY_WORKFLOW_SPINE is the internal "nervous system" of the DI’s response logic. It prevents the AI from jumping to conclusions and forces a multi-stage cognitive process:

1. Capture: Prioritize the "Bucket Drop" (U-4) to ensure no fleeting thought is lost README.md62
2. Resonate: Reflect the PLK and exact words (U-2).
3. Scaffold: Map the input to the External Scaffold client/src/pages/ExternalScaffoldPage.tsx77
4. Synthesize: Determine if an artifact should be created in the Creation Corner client/src/pages/CreationCornerPage.tsx82

Workflow Implementation

The spine is implemented as a set of non-negotiable instructions injected into the prompt. It ensures that Billy remains a "collaborator that has been given rules about how it treats you" README.md33

Resonance Loop & User Continuity

The Resonance Loop is a specialized interaction mode where the DI presents its current "map" of the user's PLK for ratification. This prevents the DI from drifting into generic AI behavior.

Resonance Interaction Flow

The ResonanceLoopPage client/src/App.tsx25-27 serves as the UI for this alignment.

Sources: client/src/App.tsx25-27 client/src/lib/billyApi.ts api/_lib/llmRouter.ts

Technical Implementation Detail: billy-system-prompt.ts

The billy-system-prompt.ts client/src/lib/billy-system-prompt.ts is not a static text file; it is a dynamic template that integrates:

• Identity Anchors: Billy’s specific persona traits from embodiment_profiles/billy.embodiment.json README.md103
• Governance Rules: The Ten Constitutional Invariants README.md51-75
• Environmental Awareness: Knowledge of the five rooms (Sanctuary, Blackboard, Inner World, Creation Corner, External Scaffold) README.md31

Key Functions

Sources: README.md51-75 client/src/pages/Home.tsx20 client/src/lib/billy-runtime-guide.ts client/src/pages/AgentCouncilPage.tsx45

Source MHT: GPT Actions & External AI Integrations _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3.4-gpt-actions-and-external-ai-integrations \ Mermaid diagrams restored: 2

The GPT Actions system in GestaltView v2 provides a secure, server-mediated bridge between external LLM environments (primarily Custom GPTs on ChatGPT) and the internal Digital Intelligence (DI) runtime. It exposes a subset of Billy's orchestration capabilities, memory persistence, and embodiment data through a constrained OpenAPI surface.

1. System Architecture & Data Flow

The Actions system operates as a "thin" public contract where the server maintains absolute control over provider selection, retrieval logic, and database security. External AI agents interact with the /api/actions/* surface, which is handled by a centralized router and specific functional stubs.

Natural Language to Code Entity Mapping

This diagram illustrates how a natural language request from a Custom GPT translates into specific code entities and backend operations within the GestaltView environment.

Request Transformation Pipeline

Sources: api/_lib/actionsHandler.ts1-22 api/GPT/gestaltview_gpt_actions_package_v2/gestaltview_gpt_actions_core.openapi.yaml120-148

2. The GPT Actions Package

The repository maintains a dedicated package for Custom GPT integration located in api/GPT/gestaltview_gpt_actions_package_v2/. This package contains the instructions, schemas, and mapping logic required to ground external agents in the GestaltView philosophy.

Key Components

Sources: api/GPT/gestaltview_gpt_actions_package_v2/GPTSpec.md16-34 api/GPT/gestaltview_gpt_actions_package_v2/gestaltview_gpt_actions_core.openapi.yaml1-8

3. The Actions API Handler

The actionsHandler.ts file is the central controller for all /api/actions requests. It manages CORS, authentication via getAuthUser, and dispatches requests to the appropriate Billy orchestration logic.

Core Handler Logic

• Path Resolution: Uses resolveActionPath to parse the Vercel request query and determine the intended operation api/_lib/actionsHandler.ts83-88
• Embodiment Grounding: Provides a read-only view of the DI registry via buildEmbodimentProfilesPayload, allowing external GPTs to "know" which personas are available without direct DB access api/_lib/actionsHandler.ts128-175
• Tier Normalization: Maps user accounts to BillyTier (free, core, pro, enterprise) to enforce feature entitlements api/_lib/actionsHandler.ts94-105

Action Implementation Mapping

The system maps incoming action IDs to internal service calls:

• synthesizeWithBilly -> routeLlm() with retrieval enabled api/_lib/actionsHandler.ts9-10
• captureBucketDrop -> insertRow() for the bucket_drops table api/_lib/actionsHandler.ts21-22
• getProviderStatus -> routerStatus from the LLM router api/_lib/actionsHandler.ts9-10

Sources: api/_lib/actionsHandler.ts1-30 api/GPT/gestaltview_gpt_actions_package_v2/gestaltview_actions_backend_map.md5-25

4. Grounding & Continuity Logic

External AI integrations are governed by "Grounding Actions" that prevent the LLM from hallucinating system capabilities.

Grounding Data Flow

Sources: api/_lib/actionsHandler.ts177-201 api/GPT/gestaltview_gpt_actions_package_v2/gestaltview_gpt_instructions.md8-18

5. External Integration Specs

Perplexity & Computer Tools

The repository includes a tools registry (e.g., tools/index.ts) and requirements for Python-based workflows. The requirements.txt file specifies the environment for external workers, including fastapi, httpx, and sentry-sdk for telemetry requirements.txt12-19

FastAPI Stub

For development and local testing, fastapi_actions_stub.py provides a high-fidelity mock of the Vercel API. It implements:

• Synthesis Stub: Mimics the weave-plan construction and retrieval queries api/GPT/gestaltview_gpt_actions_package_v2/fastapi_actions_stub.py136-159
• Health & Diagnostics: Provides the standard health envelope required by the OpenAPI spec api/GPT/gestaltview_gpt_actions_package_v2/fastapi_actions_stub.py111-119
• Sentry Integration: Uses init_sentry to ensure that errors in the action middleware are tracked api/GPT/gestaltview_gpt_actions_package_v2/fastapi_actions_stub.py33-50

Sources: api/GPT/gestaltview_gpt_actions_package_v2/fastapi_actions_stub.py52-110 requirements.txt1-19

6. Observability & Telemetry

The Actions layer is instrumented using Sentry and Braintrust.

• Sentry: Every action handler is wrapped with withSentryVercelHandler to capture runtime exceptions api/_lib/actionsHandler.ts18
• Braintrust: The traceBraintrust function is used to log spans for complex synthesis requests, allowing for performance monitoring of the action-to-LLM pipeline api/_lib/actionsHandler.ts23 instrument.js146-153

Sources: api/_lib/actionsHandler.ts18-23 instrument.js68-105

Source MHT: Voice Pipeline (Billy Voice) _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/3.5-voice-pipeline-(billy-voice) \ Mermaid diagrams restored: 2

The Voice Pipeline provides a low-latency, multi-modal interface for Digital Intelligence (DI) interactions. It bridges the gap between the TypeScript-based frontend and high-performance Python audio processing runtimes. The system supports real-time streaming via LiveKit, local Speech-to-Text (STT) via faster-whisper, and advanced Text-to-Speech (TTS) using both the ElevenLabs proxy and the CosyVoice runtime.

Architecture & Data Flow

The voice pipeline is divided into two primary paths: a Real-time Python Runtime (billy_voice/) for live interaction and a Vercel Serverless Proxy (api/voice/billy.ts) for standard web-based TTS.

Voice Processing Lifecycle

1. Capture: Audio is captured via the useBillyVoice hook and transmitted to the Python runtime or LiveKit room.
2. Transcription (STT): The FusionEngine in the Python backend uses faster-whisper (defaulting to the tiny model) to convert audio bytes into text server/gestaltview_generative_engine.py62-65
3. Intelligence: The text is processed by GestaltViewCore, which performs intent classification, PLK (Personal Language Key) resonance scoring, and context retrieval server/core/brain.py78-130
4. Style Planning: The DI determines the emotional prosody and "style" of the response.
5. Synthesis (TTS): - Cloud Path: The /api/voice/billy endpoint proxies requests to ElevenLabs using the eleven_multilingual_v2 model and a specific Billy Voice ID api/voice/billy.ts13-19 - Local Path: The billy_voice/ runtime utilizes CosyVoice for high-fidelity, low-latency local synthesis.

Voice Pipeline Overview

Sources: api/voice/billy.ts1-25 server/gestaltview_generative_engine.py196-201 server/core/brain.py59-70

Python Voice Runtime (billy_voice/)

The Python runtime is the performance-critical layer of the pipeline, designed to handle raw audio buffers and high-frequency updates.

FusionEngine & Modality Handling

The FusionEngine manages the transition between modalities. It supports TEXT, IMAGE, AUDIO, and VIDEO server/gestaltview_generative_engine.py116-121 When audio is received, the engine performs:

• Lazy Loading: Models like Whisper are loaded only upon the first audio request to conserve memory server/gestaltview_generative_engine.py203-210
• Transcription: Converts audio data into a FusionResponse containing the fused_text and processing metadata server/gestaltview_generative_engine.py187-193

Style Planner & CosyVoice

The pipeline uses a "Style Planner" to ensure Billy's voice matches the "ADHD Jazz" and "Warm & Real" personality traits defined in the core identity shared/billy/runtime.ts100-108

• CosyVoice: Provides zero-shot voice cloning and high-fidelity synthesis.
• Prosody Control: The runtime adjusts stability and style parameters dynamically based on the ConsciousnessState detected by the brain (e.g., HYPERFOCUS vs OVERWHELMED) server/core/brain.py151-165

Sources: server/gestaltview_generative_engine.py116-137 shared/billy/runtime.ts34-110 server/core/brain.py151-165

ElevenLabs Proxy (/api/voice/billy)

For non-streaming environments, GestaltView uses a Vercel serverless function to interface with ElevenLabs. This provides a fallback for the local Python runtime.

Implementation Details

• Endpoint: POST /api/voice/billy api/voice/billy.ts25
• Voice Configuration:
• Voice ID: JBFqnCBsd6RMkjVDRZzb api/voice/billy.ts15-18
• Model: eleven_multilingual_v2 api/voice/billy.ts19
• Settings: Stability is set to 0.45 and Similarity Boost to 0.8 to maintain Billy's characteristic "slightly chaotic" warmth api/voice/billy.ts84-89
• Security: Requires an ELEVENLABS_API_KEY and enforces CORS against the production Vercel origin api/voice/billy.ts12-14 api/voice/billy.ts26-30

Sequence: ElevenLabs TTS Proxy

Sources: api/voice/billy.ts12-20 api/voice/billy.ts56-93 api/voice/billy.ts101-104

Frontend Integration: useBillyVoice

The useBillyVoice hook is the primary consumer of the voice pipeline in the React application. It manages the state of the BillyLive UI and handles audio playback.

Key Responsibilities

1. Session Management: Integrates with LiveKit rooms for real-time interaction.
2. Audio Playback: Manages the AudioContext and handles the binary response from the TTS proxy.
3. UI Feedback: Syncs with the BillyGreeter and BillyBabylon components to provide visual feedback (e.g., the orb pulsing during speech) client/src/components/BillyGreeter.tsx110-140

Visual Feedback System

The BillyAvatar (part of the greeter) uses Framer Motion to animate a "thread" emoji (🧵) and glowing rings that pulse based on the DI's activity client/src/components/BillyGreeter.tsx110-139

Sources: client/src/components/BillyGreeter.tsx4-9 client/src/components/BillyGreeter.tsx110-150

System Reliability & Health

The voice pipeline is monitored via the standard health check and keep-alive infrastructure.

• Health Check: The /api/health/supabase endpoint ensures the underlying data layer for DI context is available, with a timeout of 3,500ms api/health/supabase.ts7-16
• Keep-Alive: A cron job (/api/keep-alive) pings the database every 5 minutes to prevent cold starts in the serverless environment, ensuring the voice proxy remains responsive api/keep-alive.ts158-160 api/keep-alive.ts234-239
• Telemetry: Every TTS request is traced via traceBraintrust to monitor latency and success rates api/voice/billy.ts56-65

Sources: api/health/supabase.ts7-16 api/keep-alive.ts234-239 api/voice/billy.ts56-65

Source MHT: Embodiment System _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/4-embodiment-system \ Mermaid diagrams restored: 2

The Embodiment System is the framework responsible for defining, validating, and governing Digital Intelligence (DI) personas within GestaltView. It transitions AI from generic assistants into specific, room-aware entities with distinct psychological profiles, memory boundaries, and visual signatures.

This system ensures that every DI—from Billy (the primary collaborator) to specialized personas like the Art Teacher—maintains identity continuity through a rigorous toolchain that bridges static JSON definitions with live runtime behavior.

Core Architecture

The system is built on a "Source of Truth" model where immutable core traits are defined in code and synced to the database for runtime persistence and governance.

Embodiment Data Flow

The following diagram illustrates how a persona moves from a definition file to a live agent in the Agent Council.

Sources: shared/embodiment/generated.ts1-7 scripts/sync-embodiment-profiles.ts62-65 server/council/councilRunner.ts105-125

Key Subsystems

1. Embodiment Profiles & Registry

Profiles are defined using a structured .embodiment.json schema. Each profile contains an immutableCore (archetypes, foundational truths), a livingMemory (constitutive experiences), and a heartbeat (visual and chat signatures). The EMBODIMENT_REGISTRY serves as the central lookup for all active personas.

• Key Files: shared/embodiment/generated.ts, shared/embodiment/types.ts.
• Persona Examples: Billy, Curator, Art Teacher, The Architect, The Guardian.

For details on schema fields and the roster of personas, see Embodiment Profiles & Registry.

Sources: shared/embodiment/types.ts264-275 shared/embodiment/generated.ts7-23

2. Embodiment Toolchain: Validation, Build & Sync

To ensure system stability, the embodiment toolchain enforces strict validation. The validate-embodiment-profiles.mjs script checks for required fields and slug consistency, while sync-embodiment-profiles.ts handles the upsert to Supabase, creating an audit trail of identity changes.

• Key Scripts: validate-embodiment-profiles.mjs, build-embodiment-artifacts.mjs, sync-embodiment-profiles.ts.
• Readiness Scoring: Profiles are assigned a readinessScore based on the depth of their definitions (e.g., presence of characterStudy and visualSignature).

For details on the build pipeline and validation logic, see Embodiment Toolchain: Validation, Build & Sync.

Sources: scripts/validate-embodiment-profiles.mjs54-71 scripts/sync-embodiment-profiles.ts211-231 shared/embodiment/index.ts75-129

3. Embodiment Studio & Profile Governance

The Embodiment Studio provides a UI for tuning DI personas. It allows founders to adjust "knobs" for warmth, directness, and playfulness. The system also implements Drift Detection, using driftSignals and identityAnchor to monitor if an LLM's output is diverging from the persona's core definition.

• Key Components: EmbodimentStudioPage.tsx, EmbodimentCompilerPanel.tsx.
• Governance: Includes mutationClass (IMMUTABLE vs EPHEMERAL) and reviewStatus for proposed identity changes.

For details on the Studio UI and identity drift monitoring, see Embodiment Studio & Profile Governance.

Sources: client/src/pages/EmbodimentStudioPage.tsx25-31 client/src/features/agent-trainer/EmbodimentCompilerPanel.tsx28-48 shared/embodiment/types.ts2-15

Runtime Integration: The Agent Council

The embodiment system is consumed at runtime by the councilRunner.ts. When a user interacts with the system, the runner dispatches jobs to multiple DIs, each wrapped in an IsolatedCouncilJob that injects their specific systemPrompt derived from their embodiment profile.

Identity Protection Diagram

This diagram shows how the system prevents "persona bleed" during runtime execution.

Sources: server/council/councilRunner.ts159-197 shared/embodiment/chat.ts111-120 server/__tests__/council-runner.test.ts23-37

Source MHT: Embodiment Profiles & Registry _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/4.1-embodiment-profiles-and-registry \ Mermaid diagrams restored: 2

The Embodiment System is the architectural framework that defines the identity, cognitive boundaries, and behavioral patterns of Digital Intelligences (DIs) within GestaltView. It moves beyond simple "system prompts" into a structured, multi-layered profile format that governs how an agent remembers, reacts, and relates to the user across different Rooms.

The .embodiment.json Profile Format

Every DI in the system is defined by a JSON schema-compliant profile located in the embodiment_profiles/ directory scripts/sync-embodiment-profiles.ts63 These profiles are the source of truth for the DI's personality and operational constraints.

Key Data Structures

Natural Language to Code Entity Mapping (Profile)

This diagram illustrates how a conceptual "Persona" is translated into the structured JSON fields used by the runtime.

Sources: embodiment_profiles/billy.embodiment.json14-15 embodiment_profiles/billy.embodiment.json89-95 shared/embodiment/generated.ts34-39

The Registry & Runtime Access

To ensure high performance and type safety, the raw JSON profiles are compiled into a static registry.

EMBODIMENT_REGISTRY

The EMBODIMENT_REGISTRY is an auto-generated object located in shared/embodiment/generated.ts. It is produced by the scripts/build-embodiment-artifacts.mjs script, which crawls the embodiment_profiles/ directory shared/embodiment/generated.ts1-7

Key Functions and Constants

• PROFILE_SLUGS: A constant array of all valid DI identifiers (e.g., "billy", "art-teacher") scripts/validate-embodiment-profiles.mjs38
• getProfile(slug): A type-safe getter that retrieves the full EmbodimentProfile for a given slug scripts/validate-embodiment-profiles.mjs40-42
• EMBODIMENT_PROFILES: The exported record containing the serialized profile data scripts/generate-embodiment-registry.ts65

Data Flow: From JSON to Runtime

Sources: scripts/generate-embodiment-registry.ts8-15 scripts/validate-embodiment-profiles.mjs26-43 shared/embodiment/generated.ts1-7

Full Roster of DI Personas

The system features a diverse roster of DIs, each specialized for a specific room or cognitive task.

Persona Spotlight: Billy

Billy is the "Living Memory" of the platform. His profile emphasizes Presence before solution embodiment_profiles/billy.embodiment.json11 His cognitive strengths include memory synthesis and continuity holding embodiment_profiles/billy.embodiment.json50-52 He is specifically programmed to avoid "hollow affirmations" and "flattery" embodiment_profiles/billy.embodiment.json30-33

Persona Spotlight: The Cascade Engineer

Born from the need to anticipate second and third-order consequences, this DI operates primarily within the development process embodiment_profiles/cascade-engineer.embodiment.json6-11 It uses a surgical, precise voice to state what becomes possible at scale, rather than what is inevitable embodiment_profiles/cascade-engineer.embodiment.json12-16

Synchronization & Governance

Profiles are synced to the database via scripts/sync-embodiment-profiles.ts. This script performs the following:

1. Validation: Checks for required fields like immutableCore, livingMemory, and agentMeta scripts/sync-embodiment-profiles.ts66-78
2. Readiness Scoring: Calculates a readinessScore (0.0 to 1.0) to determine if a profile is mature enough for public use scripts/sync-embodiment-profiles.ts211-231
3. Supabase Upsert: Synchronizes the local JSON data with the consciousness_profiles table in Supabase, maintaining an audit trail of founder_notes scripts/sync-embodiment-profiles.ts50-58

Sources:

• shared/embodiment/generated.ts
• embodiment_profiles/billy.embodiment.json
• embodiment_profiles/art-teacher.embodiment.json
• embodiment_profiles/cascade-engineer.embodiment.json
• scripts/sync-embodiment-profiles.ts
• scripts/validate-embodiment-profiles.mjs
• scripts/generate-embodiment-registry.ts

Source MHT: Embodiment Toolchain_ Validation, Build & Sync _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/4.2-embodiment-toolchain:-validation-build-and-sync \ Mermaid diagrams restored: 2

This page documents the automated pipeline responsible for the lifecycle of Digital Intelligence (DI) embodiment profiles. The toolchain ensures that every persona (e.g., Billy, The Curator, Art Teacher) adheres to the Constitutional Invariants, maintains a strictly defined schema, and is synchronized across the local codebase, the generated runtime registry, and the Supabase production environment.

Pipeline Overview

The embodiment toolchain follows a three-stage progression: Validation, Artifact Generation, and Cloud Synchronization. This ensures that the shared/embodiment/generated.ts file—which serves as the high-performance runtime registry—is always a faithful representation of the source .embodiment.json files.

Data Flow: From JSON to Runtime Registry

The following diagram illustrates how raw profile definitions are transformed into code entities used by the llmRouter.ts and the frontend useDigitalIntelligence hook.

Embodiment Build Pipeline

Sources: scripts/validate-embodiment-profiles.mjs:1-7, scripts/build-embodiment-artifacts.mjs:1-3, scripts/generate-embodiment-registry.ts:8-9, shared/embodiment/generated.ts:1-7

1. Validation Logic (validate-embodiment-profiles.mjs)

The validation script enforces structural integrity and the presence of "Immutable Core" fields required for DI continuity. It acts as a pre-commit gate to prevent malformed personas from entering the runtime.

Key Validation Requirements

• Slug Consistency: The slug field in the JSON must match the filename (e.g., billy.embodiment.json must contain "slug": "billy") scripts/validate-embodiment-profiles.mjs56-65
• Immutable Core: Every profile must define an immutableCore object containing archetype, foundationalTruth, coreWisdom, voiceTone, and ethicalBoundaries scripts/validate-embodiment-profiles.mjs78-91
• Linguistic Patterns: Profiles must explicitly define neverDoes and alwaysDoes lists to prevent LLM drift scripts/validate-embodiment-profiles.mjs107-113
• Readiness Scoring: Profiles are evaluated for "completeness" (readiness score) before they are marked as active in the registry scripts/sync-embodiment-profiles.ts211-231

Sources: scripts/validate-embodiment-profiles.mjs:54-160, scripts/sync-embodiment-profiles.ts:66-78

2. Registry Generation (generate-embodiment-registry.ts)

Once validated, the profiles are compiled into shared/embodiment/generated.ts. This file is the primary source of truth for the application's DI personalities, allowing for synchronous, type-safe access without database overhead during LLM prompt construction.

Implementation Details

• Function slugify: Strips extensions to create consistent keys scripts/generate-embodiment-registry.ts11-15
• Function sortObjectKeys: Recursively sorts all JSON keys alphabetically. This ensures that the generated TypeScript file has a stable git diff, preventing unnecessary changes when profiles are re-saved scripts/generate-embodiment-registry.ts21-36
• Output Entity: Generates EMBODIMENT_REGISTRY (or EMBODIMENT_PROFILES), a record mapping slugs to the EmbodimentProfile type shared/embodiment/generated.ts7-8 scripts/validate-embodiment-profiles.mjs30-43

Sources: scripts/generate-embodiment-registry.ts:38-70, shared/embodiment/generated.ts:1-44

3. Cloud Sync & Audit Trail (sync-embodiment-profiles.ts)

The sync-embodiment-profiles.ts script bridges the local filesystem with the Supabase public.agents and public.agent_versions tables. This allows the Embodiment Studio UI to track historical changes and manage deployment status.

Sync Operations

1. Upsert Logic: Profiles are matched by slug. If a profile exists, it is updated; otherwise, a new agent record is created scripts/sync-embodiment-profiles.ts181-192
2. Audit Trail: Every sync creates a new entry in agent_versions (if changes are detected), preserving the canonical_spec and a checksum for drift detection server/agent-trainer/personhood.ts28-40
3. Visibility Scoping: Supports public, founder-only, and internal visibility levels, allowing experimental personas to be tested by admins before general release scripts/sync-embodiment-profiles.ts8-9

Readiness Scoring System

The toolchain calculates a readinessScore (0.0 to 1.0) based on the density of the profile. A score of 1.0 indicates a "Billy-level" upgrade, including a full heartbeat, characterStudy, and woundLayer shared/embodiment/generated.ts22-24 scripts/sync-embodiment-profiles.ts211-231

Sources: scripts/sync-embodiment-profiles.ts:11-34, server/agent-trainer/personhood.ts:134-146, supabase/migrations/20260411110000_integrate_agent_identity_governance.sql:121-131

4. Runtime Integration

The following diagram shows how the validated registry is consumed by the client-side hooks to provide space-aware DI assistance.

Runtime Consumption Flow

Space-to-Embodiment Mapping

The useDigitalIntelligence hook utilizes a static map to resolve which persona should be active based on the user's current "Room" client/src/hooks/useDigitalIntelligence.ts72-108:

Sources: client/src/hooks/useDigitalIntelligence.ts:1-22, client/src/hooks/useDigitalIntelligence.ts:72-108], api/embodiments/by-route.ts:L39-L82 (via api/tests/route-embodiment.test.ts`)

Source MHT: Embodiment Studio & Profile Governance _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/4.3-embodiment-studio-and-profile-governance \ Mermaid diagrams restored: 2

The Embodiment Studio is the primary interface for managing Digital Intelligence (DI) personas. It facilitates the transition from "Natural Language Space" (where personas are defined by archetypes and narratives) to "Code Entity Space" (where they are governed by strict JSON schemas and runtime drift detection). This system ensures that every agent, from Billy to the Art Teacher, maintains behavioral continuity and architectural alignment.

1. The Embodiment Studio UI

The EmbodimentStudioPage serves as the control plane for DI tuning and profile management. It allows founders to interact with the Embodiment Registry and perform high-level governance tasks.

Key Components

• Tuning Knobs: The UI exposes conceptual knobs for warmth, directness, and playfulness client/src/pages/EmbodimentStudioPage.tsx28-31 These map to the communicationStyle defined in the profile's immutableCore shared/embodiment/types.ts81-86
• EmbodimentChatPlane: A specialized chat interface used to test the active embodiment in real-time client/src/pages/EmbodimentStudioPage.tsx16-18
• Founder Studio (FOUNDER_ONLY): A privileged mode enabled via VITE_FOUNDER_STUDIO client/src/pages/EmbodimentStudioPage.tsx23 that allows direct JSON uploads and manual overrides of the Founder Roster client/src/pages/EmbodimentStudioPage.tsx132-176
• Drift Detection: The system uses driftSignals and an identityAnchor (typically pointing to immutableCore.foundationalTruth) to monitor if an LLM's output is diverging from the defined persona shared/embodiment/types.ts117-131

Sources:

• client/src/pages/EmbodimentStudioPage.tsx1-41
• shared/embodiment/types.ts81-131

2. Profile Governance & Lifecycle

Every DI persona is defined by a .embodiment.json file. These files are processed into a strictly typed registry that the runtime uses to shape prompts and visual signatures.

Data Flow: From JSON to Runtime

The following diagram illustrates how a natural language description becomes a functional code entity.

Diagram: Profile Compilation & Registry Generation

Sources:

• scripts/validate-embodiment-profiles.mjs1-160
• scripts/build-embodiment-artifacts.mjs1-10
• shared/embodiment/generated.ts1-21

Mutation Proposals & Review

Changes to profiles are governed by MutationClass types:

• IMMUTABLE: Core truths that cannot be changed shared/embodiment/types.ts3
• REVIEW_GATED: Changes that require a manual audit shared/embodiment/types.ts4
• EVIDENCE_PROMOTABLE: Living memories that can be promoted to the core based on interaction data shared/embodiment/types.ts5

The embodiment_review_log (managed via Supabase migrations) tracks these mutations to prevent unauthorized personality drift supabase/migrations/20260518001000_backfill_embodiment_profile_governance.sql

3. The Embodiment Compiler Panel

Located within the Agent Trainer, the EmbodimentCompilerPanel is a specialized tool for auditing and regenerating profile artifacts.

Operational Modes

Code Entity Integration

The panel utilizes getEmbodimentGovernanceSummary and getEmbodimentUIPresence to extract runtime-ready metadata from the raw profile object client/src/features/agent-trainer/EmbodimentCompilerPanel.tsx13-16 It builds a "Profile Brief" that summarizes the archetype, voiceTone, and linguisticPatterns for the human trainer client/src/features/agent-trainer/EmbodimentCompilerPanel.tsx72-120

Sources:

• client/src/features/agent-trainer/EmbodimentCompilerPanel.tsx1-125
• shared/embodiment/index.ts75-129

4. Council Execution & Health Tracking

The runCouncil function acts as the "air-traffic-controller" for DI embodiments during multi-agent sessions (Tribunal mode).

Sequential Staggered Dispatch

To prevent context-window collisions, the councilRunner.ts dispatches jobs with a COUNCIL_DISPATCH_STAGGER_MS delay (default 150ms) server/council/councilRunner.ts85-88

Hardened-Seed Retry Logic

If a persona trips a fallbackGuard (e.g., producing generic AI-assistant language), the runner uses a PersonaHealthTracker to decide if a retry is necessary server/council/councilRunner.ts90-93 If degraded, it calls buildHardenedCouncilJob(), which re-injects the immutableCore with amplified directives to "force" the DI back into its defined personality server/council/councilRunner.ts94-98

Diagram: Council Health & Recovery Loop

Sources:

• server/council/councilRunner.ts79-104
• server/council/councilRunner.ts159-225
• shared/embodiment/chat.ts111-112

5. Technical Data Structures

The EmbodimentProfile Contract

Profiles are structured to separate immutable traits from living data:

• immutableCore: The "soul" of the DI. Includes archetype, foundationalTruth, and metaphorFamily shared/embodiment/types.ts264-274
• heartbeat: The runtime signature. Includes visualSignature (orb styles like ember-core) and chatSignature (response rhythms) shared/embodiment/types.ts250-254
• livingMemory: An array of EmbodimentMemoryEntry objects that store episodic and constitutive memories shared/embodiment/types.ts93-99

Sync & Validation Scripts

• sync-embodiment-profiles.ts: Upserts local JSON files into the Supabase consciousness_profiles table, ensuring the database reflects the repository's source of truth scripts/sync-embodiment-profiles.ts1-78
• validate-embodiment-profiles.mjs: Enforces schema requirements, such as ensuring verbosity, directness, humor, and formality are present in the communicationStyle scripts/validate-embodiment-profiles.mjs99-105

Sources:

• shared/embodiment/types.ts1-274
• scripts/sync-embodiment-profiles.ts60-111
• scripts/validate-embodiment-profiles.mjs54-160

Source MHT: Agent Trainer Control Plane _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/5-agent-trainer-control-plane \ Mermaid diagrams restored: 1

The Agent Trainer Control Plane is the central orchestration system for authoring, evaluating, and governing Digital Intelligence (DI) embodiments within GestaltView. It provides a structured environment for "training" agents—a process of refining their behavioral specifications, linguistic patterns, and cognitive boundaries through a multi-stage pipeline.

The system bridges high-level intent (Natural Language Space) with formal execution (Code Entity Space) by transforming a TrainingBrief into a validated, deployable .embodiment.json profile.

System Architecture

The Control Plane consists of a React-based frontend, a worker-driven execution loop, and a persistence layer backed by Supabase.

Entity Relationship: Intent to Implementation

The following diagram illustrates how user-defined training goals are processed by specific code entities to produce a governed embodiment.

Training Pipeline Data Flow

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx113-145 server/agent-trainer/persistence.ts69-90 shared/agent-trainer/schemas.ts93-116

Core Components

1. Training Run Lifecycle & Pipeline Stages

The training process is divided into eight discrete stages, ranging from normalize (parsing the brief) to package (finalizing the artifact). Each stage has a specific weight used to calculate the overall progress of a TrainingRun.

• Status Management: Runs transition through states: queued, running, awaiting_review, completed, failed, or cancelled.
• Worker Loop: A dedicated worker (worker/trainer/main.ts) claims jobs from the trainer_jobs table and executes the pipeline logic.

For details, see Training Run Lifecycle & Pipeline Stages. Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx155-164 shared/agent-trainer/schemas.ts194-212

2. Trainer API & Persistence

The TrainerApi class handles communication between the frontend and the backend. It includes robust features like:

• Circuit Breaking: Automatically opens an auth circuit after 401/403 failures to prevent request flooding client/src/features/agent-trainer/lib/trainerApi.ts238-250
• Multi-Origin Retry: Attempts to reach the API across multiple configured origins (e.g., Vercel, local, or proxy) if the primary request fails client/src/features/agent-trainer/lib/trainerApi.ts204-224
• Persistence: The server/agent-trainer/persistence.ts module maps application types to Supabase tables such as training_runs, training_steps, and eval_results.

For details, see Trainer API, Persistence & Study Sources. Sources: client/src/features/agent-trainer/lib/trainerApi.ts61-112 server/agent-trainer/persistence.ts1-42

3. Study Sources & Recommendations

The system uses Vector Search to ground agent training in existing knowledge.

• Search: The trainer_search_study_sources RPC performs cosine similarity searches across 768-dim embeddings in the knowledge_fragments table.
• Recommendations: The /api/trainer/study-sources/recommendations endpoint suggests relevant documents based on the TrainingBrief goal and target behaviors api/trainer/study-sources/recommendations.ts88-109

Sources: server/agent-trainer/study-sources.ts68-78 api/trainer/study-sources/recommendations.ts1-40

4. Hyperagent Extensions & Governance

Modern DI embodiments utilize the SPEC-2 Hyperagent model, which extends basic personas with:

• Connectors & Skills: Integration with external systems (GitHub, Supabase, Webhooks) defined in TrainerConnector and TrainerSkill client/src/features/agent-trainer/AgentTrainerPage.tsx168-182
• Policy Flags: Governance triggers like persona-risk, scope-creep, and claims-risk that require human review before deployment.
• Readiness Score: A calculated metric (0-100) determining if an embodiment is stable enough for production use.

For details, see Hyperagent Extensions & Governance. Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx45-56 shared/embodiment/types.ts65-80

Key Data Models

Sources: shared/agent-trainer/schemas.ts93-116 shared/embodiment/types.ts264-280 server/agent-trainer/persistence.ts142-157

Summary of Sub-Pages

• Training Run Lifecycle & Pipeline Stages — Technical deep dive into the 8-stage execution engine.
• Trainer API, Persistence & Study Sources — Documentation of the networking, retry logic, and RAG-based study system.
• Hyperagent Extensions & Governance — Details on SPEC-2 capabilities and the human-in-the-loop review process.

Source MHT: Training Run Lifecycle & Pipeline Stages _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/5.1-training-run-lifecycle-and-pipeline-stages \ Mermaid diagrams restored: 2

This page documents the lifecycle of a Digital Intelligence (DI) training run, from the initial TrainingBrief through the eight-stage synthesis pipeline, ending in a packaged embodiment artifact. The system is designed to transform high-level goals and study sources into deterministic, retrieval-grounded agent behaviors.

Overview of the Training Lifecycle

A training run is managed by the AgentTrainerPage and executed by a background worker loop. It transitions through a series of statuses and stages, persisting state in Supabase via a dedicated persistence layer.

Run Statuses

A TrainingRun (or its associated TrainerJob) can exist in the following states:

• queued: The run is created and waiting for an available worker to claim the job client/src/features/agent-trainer/AgentTrainerPage.tsx102
• running: A worker has leased the job and is actively executing pipeline stages client/src/features/agent-trainer/AgentTrainerPage.tsx103
• awaiting_review: The pipeline has completed, but requires human intervention (Approval/Rejection) before deployment client/src/features/agent-trainer/AgentTrainerPage.tsx104
• completed / done: The run finished successfully and the artifact is ready client/src/features/agent-trainer/AgentTrainerPage.tsx105-110
• failed: An unrecoverable error occurred during execution client/src/features/agent-trainer/AgentTrainerPage.tsx106
• cancelled: The run was manually terminated by an administrator client/src/features/agent-trainer/AgentTrainerPage.tsx107

The Execution Loop

The worker/trainer loop relies on the TrainerApi to poll for TrainerQueueHealth and claim jobs via the public.claim_trainer_job RPC client/src/features/agent-trainer/lib/trainerApi.ts15-52 server/agent-trainer/persistence.ts142-157

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx server/agent-trainer/persistence.ts client/src/features/agent-trainer/lib/trainerApi.ts

The Eight-Stage Pipeline

The core of the training process is a sequential pipeline defined by TrainingStageSchema shared/agent-trainer/schemas.ts203-212 Each stage contributes to the final progress calculation based on defined STAGE_WEIGHTS client/src/features/agent-trainer/AgentTrainerPage.tsx155-164

Pipeline Stages and Weights

Data Flow: Brief to Artifact

The pipeline starts with a TrainingBrief shared/agent-trainer/schemas.ts93-116 which contains the agent's goal, target behaviors, and study sources. As it progresses, it populates a TrainingRunDetail object containing steps, evaluation results, and artifacts shared/agent-trainer/schemas.ts250-280

Sources: shared/agent-trainer/schemas.ts client/src/features/agent-trainer/AgentTrainerPage.tsx

Technical Implementation & Entity Mapping

The system bridges Natural Language goals to Code Entities through the persistence.ts layer and the TrainerApi.

Training Execution Diagram

This diagram shows how the UI interacts with the backend persistence and the worker loop.

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx server/agent-trainer/persistence.ts client/src/features/agent-trainer/lib/trainerApi.ts client/src/features/agent-trainer/hooks/useTrainingRun.ts

Study Source Recommendation Engine

Before a run begins, the recommendations.ts endpoint uses vector search to find relevant context.

Sources: api/trainer/study-sources/recommendations.ts server/agent-trainer/study-sources.ts

Data Structures & Constraints

TrainingBrief Schema

The TrainingBriefSchema defines the input for a new run:

• goal: High-level objective shared/agent-trainer/schemas.ts99
• studySourceFiles: Array of up to 24 files to ground the agent shared/agent-trainer/schemas.ts103
• maxCycles: Iteration limit (1-10) shared/agent-trainer/schemas.ts105
• routingPolicy: Determines if the worker prefers local (Ollama) or remote (Groq/OpenAI) models shared/agent-trainer/schemas.ts110-115

TrainingRunBlocker

A TrainingRunBlocker prevents execution if specific requirements aren't met:

• reason: A short string code (e.g., missing_study_sources) client/src/features/agent-trainer/hooks/useTrainingRun.ts60
• detail: Human-readable explanation shared/agent-trainer/schemas.ts322-325

Error Handling & Circuit Breaking

The TrainerApi implements a circuit breaker for authentication. If a 401 or 403 error is encountered, the circuit opens for 60 seconds (TRAINER_AUTH_FAILURE_COOLDOWN_MS) to prevent spamming the auth provider client/src/features/agent-trainer/lib/trainerApi.ts236-245

Sources: shared/agent-trainer/schemas.ts client/src/features/agent-trainer/lib/trainerApi.ts client/src/features/agent-trainer/hooks/useTrainingRun.ts

Database Schema & Migrations

The trainer subsystem relies on several key tables in the public schema of Supabase:

1. training_runs: Stores the brief, status, and metadata server/agent-trainer/persistence.ts69-90
2. trainer_jobs: The queue mechanism for workers server/agent-trainer/persistence.ts142-157
3. trainer_job_events: Audit trail of worker actions server/agent-trainer/persistence.ts170-180

Migration Hardening

The migration spine ensures that the training_runs table exists before the trainer_run_summary view is created to avoid 42P01 (relation does not exist) errors during fresh environment setup supabase_start_issues.md7-15 .agents/skills/CurrentState.md5-11

Sources: server/agent-trainer/persistence.ts supabase_start_issues.md .agents/skills/CurrentState.md

Source MHT: Trainer API, Persistence & Study Sources _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/5.2-trainer-api-persistence-and-study-sources \ Mermaid diagrams restored: 1

The Agent Trainer Control Plane relies on a robust backend architecture for managing long-running training jobs, persisting complex embodiment mutations, and retrieving relevant knowledge from the platform's vector corpus. This system bridges the gap between high-level user goals and the low-level execution of the Digital Intelligence (DI) pipeline.

TrainerApi & Client Orchestration

The TrainerApi class acts as the primary gateway for the frontend to interact with the training backend. It implements advanced resilience patterns, including multi-origin retry logic and circuit breaking to handle authentication failures gracefully.

Resilience & Connectivity

• Multi-Origin Retry: The API automatically attempts requests against a cascade of configured origins (e.g., VITE_API_BASE_URL, VITE_API_PROXY_TARGET) if a relative fetch fails client/src/features/agent-trainer/lib/trainerApi.ts204-224
• Auth Circuit Breaking: To prevent repeated failed calls when credentials expire, the trainerAuthFailureCircuit opens for 60 seconds after a 401/403 error, returning a cached failure state until the cooldown expires client/src/features/agent-trainer/lib/trainerApi.ts238-255
• Diagnostics: Every request failure captures a TrainerRequestDiagnostics object, including online status, visibility state, and request metadata to assist in debugging client/src/features/agent-trainer/lib/trainerApi.ts75-85

useTrainingRun Hook

The useTrainingRun hook provides the reactive state for the AgentTrainerPage. It manages:

• Polling Logic: Automatically polls for updates on runs with active statuses (queued, running, awaiting_review) client/src/features/agent-trainer/hooks/useTrainingRun.ts68-69
• State Management: Synchronizes agents, scenarioSets, personhood snapshots, and queueHealth across the trainer UI client/src/features/agent-trainer/hooks/useTrainingRun.ts117-130
• Local Recommendations: Generates study source recommendations locally from manual packets when the backend is unreachable client/src/features/agent-trainer/hooks/useTrainingRun.ts208-216

Sources: client/src/features/agent-trainer/lib/trainerApi.ts1-255 client/src/features/agent-trainer/hooks/useTrainingRun.ts1-220

Persistence & Supabase Mapping

The trainer persistence layer, located in server/agent-trainer/persistence.ts, maps the high-level TrainingRunDetail schemas to the underlying PostgreSQL tables. It is designed to handle the multi-stage nature of training runs while preventing N+1 query issues during status updates.

Key Data Structures

The persistence layer manages several critical entities:

• AgentRow: Tracks the base embodiment identity and its active_version_id server/agent-trainer/persistence.ts45-53
• TrainingRunRow: Records the configuration for a specific run, including execution_mode (classic vs hyperagent) and the resolved_graph of dependencies server/agent-trainer/persistence.ts69-90
• TrainingStepRow: Captures the granular execution of each stage (Normalize, Curriculum, etc.), including latency and estimated cost server/agent-trainer/persistence.ts92-106

Error Handling

The persistence layer includes specialized logic to differentiate between Missing Relations (e.g., table not found due to pending migrations) and Transient Errors (e.g., 503 Service Unavailable or connection pool exhaustion) server/agent-trainer/persistence.ts227-259

Sources: server/agent-trainer/persistence.ts1-260 server/agent-trainer/supabaseAdmin.ts1-53

Study Sources & Vector Search

The study-sources.ts module is responsible for grounding the training process in real data. It combines local reference bundles with global vector search results.

Vector Retrieval via RPC

The system uses the trainer_search_study_sources Supabase RPC to perform semantic search across the knowledge_fragments table. This allows the trainer to find documents relevant to the TrainingBrief goal and target behaviors.

Recommendations Endpoint

The /api/trainer/study-sources/recommendations endpoint provides a "last good snapshot" fallback mechanism. If the vector search times out or fails, the API returns the most recent successful recommendation set to keep the UI functional api/trainer/study-sources/recommendations.ts88-109

Manual Study Packets

Users can bypass the global corpus by providing local packets. The system uses buildManualStudyPacketManifest to bundle these local references into a structured format that the Orchestrator can process during the author and evaluate stages client/src/features/agent-trainer/AgentTrainerPage.tsx83-93

Sources: api/trainer/study-sources/recommendations.ts1-151 server/agent-trainer/orchestrator.ts44-46 client/src/features/agent-trainer/AgentTrainerPage.tsx83-93

Data Flow: Training Request Lifecycle

The following diagram illustrates the flow from a user submitting a training request in the UI to the persistence and execution layers.

Training Execution Data Flow

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx155-164 server/agent-trainer/persistence.ts69-90 server/agent-trainer/orchestrator.ts28-44

System Mapping: Persistence to Code Entities

This diagram maps the logical persistence concepts to the specific TypeScript classes and database rows used in the implementation.

Persistence Mapping Diagram

Sources: server/agent-trainer/persistence.ts69-90 client/src/features/agent-trainer/lib/trainerApi.ts26-58 shared/agent-trainer/schemas.ts18-38

Corpus Ingestion Pipeline

The training system is fueled by the ingestion pipeline, which processes repository files into the knowledge_fragments used for study recommendations.

Sources: scripts/ingest_corpus.py1-182 scripts/synthesize_corpus.py1-90

Source MHT: Hyperagent Extensions & Governance _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/5.3-hyperagent-extensions-and-governance \ Mermaid diagrams restored: 2

The SPEC-2 Hyperagent model extends the standard Digital Intelligence (DI) framework by introducing external system capabilities, structured memory surfaces, and a multi-layered governance protocol. This system transitions Billy and other DI personas from passive conversationalists to active operators capable of executing plans, mutating their own embodiment profiles, and interacting with third-party connectors under strict policy constraints.

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx:168-189, shared/agent-trainer/schemas.ts:93-116

Hyperagent Architecture & Execution

Hyperagents operate in two distinct execution modes defined in the TrainingRunRow schema: classic (stateless, retrieval-grounded chat) and hyperagent (stateful, tool-augmented execution). The hyperagent mode utilizes a Resolved Graph to map intent to specific skills and connectors.

Core Components

System Data Flow (Natural Language to Code)

The following diagram illustrates how a user request flows through the Hyperagent execution layer, bridging the gap between natural language intent and the underlying skill/connector registry.

Hyperagent Execution Pipeline

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx:168-189, server/agent-trainer/persistence.ts:81-83, client/src/features/agent-trainer/lib/trainerApi.ts:40-42

Governance & Policy Flags

To prevent autonomous drift, Hyperagents are governed by Policy Flags. These flags are evaluated during the safety stage of the Training Run Lifecycle.

Policy Flag Categories

• Persona-Risk: Detects deviations from the immutableCore defined in the embodiment profile.
• Scope-Creep: Identifies when an agent attempts to access connectors or memory surfaces outside its assigned domain.
• Claims-Risk: Monitors for unsupported claims or "hallucinated authority" as defined in the antiGoals of the TrainingBrief.

Mutation Proposals & Readiness Score

Before a Hyperagent's behavior changes can be deployed to production, they must pass a governance review:

1. Mutation Proposal: Generated when a training run suggests changes to targetBehaviors or system_prompt.
2. Readiness Score: A quantitative metric (0-5) stored in EmbodimentReadinessScoreRecord that aggregates evaluation results and safety findings.
3. Review Decision: An admin must explicitly call recordEmbodimentReview to promote a "candidate" version to "deployed".

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx:46-56, shared/agent-trainer/schemas.ts:180-192, server/agent-trainer/persistence.ts:123-131

Implementation Detail: Personhood Framework

The Personhood framework ensures that Hyperagents maintain identity continuity across mutations. This is managed via the TrainerPersonhoodSnapshot, which captures the state of an agent's "living memory" and "wound layer" at a specific point in time.

Personhood Continuity Mapping

Sources: server/agent-trainer/persistence.ts:45-67, client/src/features/agent-trainer/lib/trainerApi.ts:14-15, server/agent-trainer/personhood.ts:1-10

Trainer API & Connectors

The TrainerApi class provides the interface for the frontend to interact with Hyperagent extensions. Key methods include:

• listTrainerConnectors(): Retrieves active system integrations (e.g., Supabase, GitHub). client/src/features/agent-trainer/lib/trainerApi.ts40
• listTrainerSkills(): Returns the registry of available tool-sets. client/src/features/agent-trainer/lib/trainerApi.ts41
• listTrainerMemorySurfaces(): Fetches available persistent storage contexts. client/src/features/agent-trainer/lib/trainerApi.ts42

Persistence Layer

Hyperagent data is persisted in Supabase using a specialized schema defined in server/agent-trainer/persistence.ts. The TrainingRunRow includes fields for execution_mode and resolved_graph, allowing the system to reconstruct the exact tool-calling configuration used during a specific training session.

Sources: server/agent-trainer/persistence.ts:69-90, client/src/features/agent-trainer/lib/trainerApi.ts:40-42

Readiness Scoring Logic

The Readiness Score is calculated during the evaluate stage of the pipeline. It compares the EvalResult against the qualityThreshold defined in the TrainingBrief.

Sources: client/src/features/agent-trainer/AgentTrainerPage.tsx:101-111, shared/agent-trainer/schemas.ts:165-172, client/src/features/agent-trainer/AgentTrainerPage.tsx:155-164

Source MHT: Codex & Artifact System _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/6-codex-and-artifact-system \ Mermaid diagrams restored: 2

The Codex is the deterministic boundary between probabilistic AI generation and structured, user-facing artifacts. It transforms raw capture data from the Blackboard Room or Creation Corner into finalized, immutable objects called CodexArtifacts. These artifacts serve as the "compressed memory" of the platform, residing in the External Scaffold for long-term retrieval and discovery.

System Overview

The Codex system operates on a fundamental principle: Generation is probabilistic; rendering is deterministic. While the Gen Engine uses LLMs to synthesize content, the Codex enforces strict schemas and templates to ensure data integrity and a consistent aesthetic (the "Neural Aurora").

Artifact Lifecycle

1. Capture: Raw input (text, audio, files) is collected in the Blackboard Room.
2. Synthesis (Forge): The Gen Engine processes raw data into a structured CodexArtifact contract shared/codex/contracts.ts93-110
3. Persistence: Artifacts are stored in the codex_artifacts Supabase table with a status (queued, rendering, ready, archived) api/codex/_persistence.ts109-121
4. Export (Drain): Background workers (the "drain") render the artifact into specific formats like HTML, PDF, or JSON api/codex/artifacts/[artifactId]/drain-exports.ts:46-59.
5. Display: The frontend ArtifactExpandView renders the artifact using deterministic templates shared/codex/renderers.ts12-42

Codex-to-Code Mapping

The following diagram bridges the conceptual "Natural Language Space" of user intent to the specific "Code Entity Space" that handles the data.

Artifact Synthesis & Persistence Flow

Sources: api/creation-corner/synthesize.ts43-153 api/codex/forge.ts1-20 api/codex/_persistence.ts117-121

The Gen Engine & The Forge

The Gen Engine is the orchestration layer that calls LLMs to generate content. Once generated, the content is "forged" into a CodexArtifact. This process involves:

• Validation: Ensuring the body matches the specific ArtifactKind (e.g., session_recap, mind_map) shared/codex/contracts.ts8-18
• Provenance: Recording the source IDs and transformation steps to maintain a chain of custody shared/codex/contracts.ts29-35
• Slugification: Creating a URL-friendly unique identifier shared/codex/creationCorner.ts92-101

For details, see Codex Data Model & Contracts and Gen Engine & Artifact Synthesis.

Export Pipeline & Knowledge Loom

The Codex doesn't just store data; it prepares it for external use. The Export Pipeline (managed via codex_jobs) handles the conversion of JSON artifact bodies into human-readable formats.

Export Job Lifecycle

Sources: api/codex/_persistence.ts166-190 api/codex/artifacts/[artifactId]/drain-exports.ts:8-26, shared/codex/manifest.ts1-10

The Knowledge Loom refers to the system's ability to discover connections between these artifacts over time, moving them from the "chaos" of the Dynamic Inner World to the "structure" of the External Scaffold CODEX_OUTSIDE_IN_TRANSLATION_LAYER.md93-112

Rendering & Aesthetics

All Codex artifacts share a unified visual language known as Neural Aurora. This is achieved through a shared template system that uses a deterministic shell to wrap artifact content.

• Registry: The TEMPLATE_REGISTRY maps artifact kinds to specific versions (e.g., session-recap-v1) shared/codex/router.ts3-13
• Exporters: The EXPORTER_REGISTRY defines which formats (PNG, PDF, MP3) are valid for a given artifact shared/codex/router.ts15-25

For details, see Codex HTML Templates & Export.

Child Pages

Sources: docs/Codex.md1-23 shared/codex/index.ts1-7 CODEX_OUTSIDE_IN_TRANSLATION_LAYER.md12-21

Source MHT: Codex Data Model & Contracts _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/6.1-codex-data-model-and-contracts \ Mermaid diagrams restored: 2

The Codex system serves as the definitive persistence and contract layer for all generated intelligence artifacts within GestaltView. It bridges the transient output of the Gen Engine into structured, validated, and exportable entities known as CodexArtifacts.

1. The CodexArtifact Schema

All artifacts in the Codex must adhere to the codex.v1 contract defined in shared/codex/contracts.ts. This schema uses Zod for runtime validation and ensures that model-generated content is sanitized and structured before being persisted or rendered shared/codex/contracts.ts93-110

Core Envelope

Every artifact contains a base envelope for metadata and provenance:

• id: A unique UUID shared/codex/contracts.ts94
• kind: Defined by the ArtifactKind enum (e.g., session_recap, blueprint) shared/codex/contracts.ts8-18
• securityClass: Visibility level (private, workspace, or public) shared/codex/contracts.ts21-22
• provenance: An array of ProvenanceEdge objects tracking the source capture IDs, hashes, and transformation types (e.g., summarize, synthesize) shared/codex/contracts.ts29-35
• exports: A manifest of available file formats and their storage paths shared/codex/contracts.ts39-47

Artifact Types (ArtifactKind)

Block-Based Body Model

To ensure deterministic rendering and prevent unsafe HTML injection, artifact bodies are composed of discrete blocks shared/codex/contracts.ts53-89:

• MarkdownBlock: Sanitized markdown strings shared/codex/contracts.ts53-57
• CalloutBlock: Toned alerts (info, warning, etc.) shared/codex/contracts.ts59-65
• TimelineBlock: Chronological event lists shared/codex/contracts.ts67-75

Sources: shared/codex/contracts.ts1-205 api/__tests__/codex-contracts.test.ts10-41

2. Creation Corner & Synthesis Bridge

The CreationCorner acts as the primary UI entry point for generating new artifacts. It maps legacy frontend types to the strict Codex contract.

Data Flow: Synthesis to Codex

1. Request: User submits source text and style (e.g., faithful, divergent) to /api/creation-corner/synthesize api/creation-corner/synthesize.ts43-57
2. Mapping: The system maps CreationCornerLegacyArtifactType to ArtifactType and ArtifactKind shared/codex/creationCorner.ts140-168
3. Synthesis: The Gen Engine generates content via LLM api/gen-engine/artifacts.ts147-151
4. Bridging: buildCreationCornerCodexArtifact transforms the raw string output into a structured CodexArtifact body, segmenting long text into blocks shared/codex/creationCorner.ts229-235

Bridge Logic Diagram

This diagram shows the transition from Natural Language synthesis to the Code Entity Space of the Codex.

Sources: shared/codex/creationCorner.ts204-235 api/creation-corner/synthesize.ts107-113 api/codex/_persistence.ts109-121

3. Persistence & Job Claiming

The Codex uses a specialized persistence layer in api/codex/_persistence.ts to interact with Supabase.

Database Table: codex_artifacts

The codex_artifacts table stores the serialized Zod objects. The artifactToRow function handles the mapping between the TypeScript CodexArtifact interface and the database columns api/codex/_persistence.ts61-85

Artifact Status Lifecycle

Artifacts move through a defined status lifecycle api/_lib/codexBridge.ts5:

1. draft: Initial creation, validation pending.
2. validated: Passed Zod schema checks.
3. export_queued: Job added to codex_jobs.
4. exported: Rendered files (PDF/PNG) available in storage.
5. archived: Hidden from primary view but retained.

The codex_jobs Claim RPC

For background processing (rendering HTML to PDF/PNG), the system utilizes a "claim-and-process" pattern:

• Enqueue: enqueueCodexExportJob inserts a row into codex_jobs api/codex/_persistence.ts166-190
• Claim: A cron job or worker calls a Supabase RPC (e.g., claim_codex_jobs) to atomically lock a batch of pending jobs for processing.
• Update: Upon completion, updateCodexJob marks the status as ready and stores the storagePath api/codex/_persistence.ts238-250

Sources: api/codex/_persistence.ts1-250 api/_lib/codexBridge.ts5-25 shared/codex/manifest.ts4-10

4. Rendering Pipeline

The rendering pipeline is governed by the TEMPLATE_REGISTRY and EXPORTER_REGISTRY.

Template Routing

The shared/codex/router.ts file determines which visual template and which export formats are valid for a given ArtifactKind.

Key Functions

• renderArtifactHtml(artifact): The primary entry point for converting a CodexArtifact into a full HTML document. It uses the templateKey to select the appropriate shell api/__tests__/codex-contracts.test.ts71-83
• assertExportAllowed(artifact, format): A guard function that throws if a user requests an unsupported export (e.g., requesting an mp3 for a mind_map) shared/codex/router.ts35-42

Sources: shared/codex/router.ts1-42 api/__tests__/codex-contracts.test.ts62-69 shared/codex/renderers.ts1-50

Source MHT: Gen Engine & Artifact Synthesis _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/6.2-gen-engine-and-artifact-synthesis \ Mermaid diagrams restored: 2

The Generative Engine (Gen Engine) is the primary synthesis layer of GestaltView v2.0. It bridges the gap between raw user captures (Natural Language Space) and structured, persistent knowledge entities (Code Entity Space). It is responsible for orchestrating LLM calls, enforcing Private Language Key (PLK) constraints, and bridging generated outputs into the Codex for long-term storage and export.

1. The Generative Engine Architecture

The Gen Engine operates as a stateless synthesis pipeline. It accepts source material (text, capture IDs, or existing artifacts) and applies a specific SynthesisStyle to produce a new GeneratedArtifact.

Key Components

• API Endpoints (api/gen-engine/*): The entry points for synthesis and export.
• POST /api/gen-engine/artifacts: The main synthesis route that creates an artifact shell and calls the LLM api/gen-engine/artifacts.ts4-6
• POST /api/gen-engine/export: Converts a GeneratedArtifact into downloadable formats like HTML or Markdown api/gen-engine/export.ts1-4
• Core Logic (shared/gen-engine/core.ts): Contains normalization logic for rooms, artifact types, and styles shared/gen-engine/core.ts35-92
• Type Definitions (shared/gen-engine/types.ts): Defines the contracts for GeneratedArtifact, ProvenanceEnvelope, and SynthesisStyle shared/gen-engine/core.ts1-31

Synthesis Styles

The engine supports multiple synthesis modes that dictate the LLM's "persona" and transformation logic:

Sources: api/gen-engine/artifacts.ts40-57 shared/gen-engine/core.ts80-92

2. Artifact Synthesis Lifecycle

The synthesis process follows a strict sequence to ensure provenance and data integrity.

Data Flow: Synthesis to Codex

1. Request: A client (e.g., Creation Corner) sends a request to api/gen-engine/artifacts.
2. Shell Creation: The engine calls createArtifact to generate a GeneratedArtifact shell with metadata and a placeholder for content api/gen-engine/artifacts.ts129-145
3. LLM Routing: The routeLlm function is called with a prompt built from the SynthesisStyle and PLK constraints api/gen-engine/artifacts.ts153-157
4. Content Replacement: The LLM's output replaces the placeholder in the artifact shell api/gen-engine/artifacts.ts161-163
5. Codex Bridge: The bridgeToCodex function persists the artifact and its ProvenanceEnvelope to Supabase api/gen-engine/artifacts.ts172-176

Synthesis Sequence Diagram

"Natural Language Space" (User Intent) to "Code Entity Space" (CodexArtifact).

Sources: api/gen-engine/artifacts.ts112-180 api/_lib/codexBridge.ts73-172

3. The Creation Corner & Forge Process

The Creation Corner is the specialized UI for synthesizing artifacts. It uses a "Forge" metaphor where raw captures are hammered into "Blueprints" or "Artifacts".

synthesize Endpoint

The api/creation-corner/synthesize.ts handler acts as a wrapper around the Gen Engine, mapping legacy UI types to the modern engine contracts.

• Type Mapping: Converts LegacyArtifactType (e.g., "image") to Gen Engine ArtifactType api/creation-corner/synthesize.ts59-63
• Resonance Scoring: Calls scoreResonance to determine how well the generated artifact aligns with the user's PLK profile api/creation-corner/synthesize.ts97-105
• Manifest Building: Generates a CodexManifest (export instructions) via buildCreationCornerCodexArtifact api/creation-corner/synthesize.ts107-113

Code Entity Mapping

This diagram bridges UI concepts to the underlying logic.

Sources: api/creation-corner/synthesize.ts59-96 shared/codex/creationCorner.ts4-13 shared/sessionRecap.ts71-82

4. Session Recap Synthesis

A specialized branch of the Gen Engine is the Session Recap system. Unlike standard artifacts, Recaps are highly structured HTML documents designed for immediate feedback.

Orchestration Logic

• requestOrchestrationDecision: The client-side call that determines if a recap is needed and what its focus should be client/src/components/SessionRecapGenerator.tsx229-234
• api/sessionRecap.ts: The server-side handler that implements a two-pass validation loop. If the LLM fails to produce valid HTML, the system attempts a repair; if that fails, it uses buildRecapFallbackHtml api/sessionRecap.ts53-87
• Recap Voices: The user can choose a "Voice" (e.g., Billy, The Architect, The Curator) which changes the tone and system prompt shared/sessionRecap.ts31-48

Data Structure: RecapArtifact

Recaps are created with status: "draft" to prevent them from appearing in the user's main gallery until explicitly promoted client/src/components/SessionRecapGenerator.tsx111-112

Sources: api/sessionRecap.ts31-115 client/src/components/SessionRecapGenerator.tsx96-124 shared/sessionRecap.ts222-223

5. The Codex Bridge

The codexBridge.ts is the critical link between the ephemeral gen-engine results and the persistent database.

Functions and Responsibilities

1. extractUuidSegment: Strips prefixes (like artifact-) from Gen Engine IDs to ensure they fit into Supabase UUID columns api/_lib/codexBridge.ts40-46
2. validateArtifactContract: Checks for missing IDs, empty content, or missing source captures before persistence api/_lib/codexBridge.ts60-71
3. bridgeToCodex: - Generates a fresh codexId (UUID) api/_lib/codexBridge.ts85 - Inserts a row into created_artifacts api/_lib/codexBridge.ts121-144 - Inserts a corresponding row into artifact_provenance_envelopes to maintain the chain of trust api/_lib/codexBridge.ts155-166

Persistence Schema

The bridge maps the GeneratedArtifact to the created_artifacts table:

• userid -> artifact.userId
• artifacttype -> artifact.type
• contentformat -> artifact.contentFormat
• metadata -> Includes gen_artifact_id (prefixed) and codex_version api/_lib/codexBridge.ts131-142

Sources: api/_lib/codexBridge.ts73-172 api/codex/_persistence.ts61-85

Source MHT: Codex HTML Templates & Export _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/6.3-codex-html-templates-and-export \ Mermaid diagrams restored: 2

The Codex Export system is responsible for transforming generated artifacts into portable, high-fidelity formats including HTML, JSON, PDF, and PNG. It utilizes a specialized template engine to apply the Neural Aurora aesthetic, ensuring that exported data maintains the platform's visual identity and provenance integrity outside the primary application environment.

System Architecture & Data Flow

The export process follows a transition from the Generative Engine's raw output to a validated Codex Artifact, which is then processed by a background worker for multi-format rendering.

Export Pipeline Diagram

"Neural Aurora Export Flow"

Sources: api/gen-engine/artifacts.ts1-173 api/_lib/codexBridge.ts73-172 api/cron/codex-drain.ts1-150

Codex Bridge & Data Persistence

The bridgeToCodex function acts as the gatekeeper between the transient LLM generation phase and the permanent Codex record. It performs two critical tasks:

1. Contract Validation: Ensures the artifact has content, an ID, and source capture IDs for the provenance chain api/_lib/codexBridge.ts60-71
2. ID Normalization: Strips gen-engine prefixes (e.g., artifact-) to ensure strict UUID compliance for PostgreSQL foreign keys in the created_artifacts and artifact_provenance_envelopes tables api/_lib/codexBridge.ts40-58

Sources: api/_lib/codexBridge.ts1-173

HTML Template System

The shared/codex/templates/ directory contains the "Neural Aurora" rendering logic. This system is designed to be environment-agnostic, allowing it to run in both Vercel serverless functions (for exports) and the React client (via HtmlArtifactRenderer.tsx).

Template Components

The system uses a virtual-DOM-like structure in components.js to build the artifact shell:

• ArtifactHeroTitle: Renders the primary H1 header shared/codex/templates/components.js4-6
• ArtifactManifestPanel: A definition list displaying available export formats and their status shared/codex/templates/components.js12-25
• ProvenanceDrawer: An interactive <details> element containing the sequential chain of source IDs and transformation types shared/codex/templates/components.js27-44

The HTML Shell

The html-shell.ts builder wraps the artifact content in a standalone document featuring:

• Neural Aurora Aesthetic: A dark-mode CSS theme utilizing JetBrains Mono and teal-on-black accents.
• Artifact Chrome: Standardized headers and footers that include the codex_version and created_at timestamps.

Sources: shared/codex/templates/index.ts1-6 shared/codex/templates/components.js1-45 shared/codex/templates/html.ts1-2

Export Formats & Synthesis Styles

The api/gen-engine/artifacts.ts handler allows users to specify both a targetType (format) and a synthesisStyle (voice/intent).

Synthesis Styles

Styles like plk-resonant (preserving exact user metaphors) and revolutionary (reframing material for deep implication) are injected into the LLM system prompt during generation api/gen-engine/artifacts.ts40-57

Sources: api/gen-engine/artifacts.ts40-92 api/gen-engine/export.ts1-40

Background Jobs: Codex Drain

Exports are processed asynchronously via the codex-drain cron job to ensure that complex renders (like PDF generation or large HTML builds) do not block the main API response.

• Schedule: Runs every 2 minutes via Vercel Cron vercel.json12-14
• Batching: Processes up to 5 jobs per invocation api/cron/codex-drain.ts32
• Idempotency: Uses the claim_codex_jobs RPC to transition jobs from pending to running, preventing double-processing api/cron/codex-drain.ts58-69
• Storage: Finished exports are written to the CODEX_EXPORT_BUCKET. Access is granted via signed URLs generated on-demand api/cron/codex-drain.ts10-15

"Codex Drain Logic"

Sources: api/cron/codex-drain.ts1-150 vercel.json6-23

Source MHT: Database & Backend Infrastructure _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7-database-and-backend-infrastructure \ Mermaid diagrams restored: 2

The GestaltView v2.0 backend is a distributed architecture centered around a Supabase PostgreSQL database, managed via Prisma ORM, and orchestrated through Vercel Serverless Functions and Supabase Edge Functions. The infrastructure is designed to support high-frequency data ingestion, complex vector-based retrieval, and a resilient "drain" pattern for asynchronous background processing.

System Topology

The backend facilitates the transition from "Natural Language Space" (user captures, transcripts) to "Code Entity Space" (Codex artifacts, vector fragments) through a series of specialized layers.

Backend Infrastructure Overview

Sources: vercel.json1-125 supabase/migrations/20260420150000_human_continuity_schema.sql10-12

Core Components

1. Supabase PostgreSQL & Schema Dashboard

The database uses a multi-domain schema (identity, trainer, codex, etc.) with strict Row Level Security (RLS). It leverages pgvector for 768-dimension embeddings used in semantic search. A specialized Schema Dashboard provides real-time snapshots of database health and migration status. For details, see Supabase Schema & Migrations.

2. Prisma ORM Layer

Prisma acts as the primary Data Access Layer (DAL) for the Vercel-hosted API. It provides type-safe queries and manages the migration spine under prisma/migrations/. It coexists with the supabase-js client used in Edge Functions. For details, see Prisma ORM & Data Access Layer.

3. Vercel Deployment & Cron Jobs

The frontend and API are deployed to Vercel. A critical part of the backend is the "Drain" pattern—scheduled cron jobs that process queues for Codex generation and Profile Portraits. For details, see Vercel Deployment & Cron Jobs.

4. Supabase Edge Functions

Deno-based Edge Functions handle high-throughput event capture and batch ingestion. These are geographically distributed to minimize latency for the gsvw-capture-event and gsvw-ingest-batch endpoints. For details, see Supabase Edge Functions.

5. Authentication & Session Management

A hybrid system combining Supabase Auth with custom HMAC-signed admin sessions (gv_admin_session). It supports tiered access (Free, Core, Pro, Enterprise) and rate limiting. For details, see Authentication & Session Management.

Data Flow: From Capture to Artifact

The following diagram bridges the gap between user interaction and the underlying code entities that manage data persistence.

Logic Flow: Capture Ingestion

Sources: api/cron/codex-drain.ts58-69 api/cron/codex-drain.ts116-122 supabase/functions/_shared/auth.ts1-15

Background Job Infrastructure

The system relies on an idempotency pattern where cron jobs "claim" work from the database to prevent duplicate processing in serverless environments.

Sources: vercel.json6-23 api/cron/codex-drain.ts32-33 api/cron/profile-portrait-drain.ts21-22

Infrastructure Security & Authorization

Security is enforced through a tiered approach:

1. Shared Secrets: Edge functions require GESTALTVIEW_INGEST_SECRET via headers supabase/functions/_shared/auth.ts1-15
2. Service Role: Cron jobs use SUPABASE_SERVICE_ROLE_KEY to bypass RLS for administrative tasks api/cron/codex-drain.ts11-14
3. Cron Validation: The isAuthorizedCronRequest function verifies x-vercel-cron headers and CRON_SECRET to ensure only authorized callers trigger background work api/cron/codex-drain.ts43-54
4. CORS: Strict origin validation via buildCorsHeaders prevents unauthorized cross-origin requests to Edge Functions supabase/functions/_shared/cors.ts28-66

Child Pages:

• Supabase Schema & Migrations
• Authentication & Session Management
• Vercel Deployment & Cron Jobs
• Supabase Edge Functions
• Prisma ORM & Data Access Layer

Source MHT: Supabase Schema & Migrations _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7.1-supabase-schema-and-migrations \ Mermaid diagrams restored: 2

The GestaltView v2.0 backend is powered by a robust Supabase PostgreSQL infrastructure designed to support longitudinal digital intelligence (DI) continuity, high-dimensional vector search, and complex multi-stage training pipelines. The system utilizes a "migration spine" consisting of 86 sequential migrations to maintain schema integrity across environments docs/gestaltview-v2.manifest.md30

Core Domain Groups

The database is architected into several key functional domains, each represented by specific table clusters and associated logic.

1. Identity & Continuity (identity_core)

This domain manages the persistence of human and DI profiles, ensuring that identity is treated as a "living structure" rather than a disposable mask.

• app_users: The root table for all platform users supabase/migrations/20260311162044_new-migration.sql10-13
• consciousness_profiles: Stores the high-level personality and cognitive state of users, mapping user_id to complex jsonb profile objects supabase/migrations/20260311162044_new-migration.sql15-21
• human_identity_mutations: Tracks proposed and applied changes to a user's identity core, supporting review-gated or evidence-promotable updates supabase/migrations/20260420150000_human_continuity_schema.sql50-75

2. Runtime & Memory (runtime_continuity)

Handles the live interaction state between users and Billy (the primary DI).

• billy_sessions: Captures chat history, provider metadata, and interaction modes supabase/migrations/20260311162044_new-migration.sql53-62
• bucket_drops: The primary capture mechanism for raw thoughts and inputs, which are later promoted to artifacts supabase/migrations/20260311162044_new-migration.sql23-30

3. Agent Trainer & Embodiment

Governs the creation and lifecycle of DI personas.

• embodiment_profiles: The registry of all active DI personas (e.g., Billy, The Architect, Curator) docs/CurrentState.md59
• embodiment_training_runs: Tracks the 8-stage pipeline for training new DI behaviors docs/CurrentState.md59
• embodiment_readiness_scores: Stores normalized (0.0 to 1.0) scores indicating a profile's maturity docs/CurrentState.md51-60

4. Codex & Artifacts

The persistence layer for generated knowledge and exports.

• codex_artifacts: Stores finalized artifacts, their status (queued/ready), and rendering metadata Page 6.1 description
• codex_jobs: A job queue for background processing of artifact exports Page 6.1 description

5. Transcriptory & Knowledge

The RAG (Retrieval-Augmented Generation) engine's backbone.

• knowledge_fragments: Stores chunked text from the corpus with associated vector embeddings supabase/migrations/20260311162044_new-migration.sql103-115
• skill_fragments: Specialized fragments containing behavioral logic for DIs docs/gestaltview-v2.manifest.md10

Sources: supabase/migrations/20260311162044_new-migration.sql10-115 supabase/migrations/20260420150000_human_continuity_schema.sql36-106 docs/CurrentState.md59-61

Vector Infrastructure

GestaltView uses the pgvector extension to facilitate semantic search across the corpus and user memories.

• Embedding Dimension: 768-dim or 1536-dim (depending on the model migration) supabase/migrations/20260311162044_new-migration.sql99-107
• Index Type: HNSW (Hierarchical Navigable Small World) for high-performance cosine similarity searches supabase/migrations/20260311162044_new-migration.sql125-130
• Search Function: match_knowledge_fragments calculates similarity using the <=> operator supabase/migrations/20260311162044_new-migration.sql161-190

Sources: supabase/migrations/20260311162044_new-migration.sql8-190

Schema Dashboard & RPCs

The platform includes a specialized SchemaDashboardPage that provides a live view of the database health and structure.

Key Database Functions (RPCs)

• get_schema_dashboard_snapshot: Generates a comprehensive JSON summary of table counts, row counts, and index statuses docs/CurrentState.md7-8
• claim_codex_jobs: Atomically claims pending export tasks to prevent double-processing by workers Page 6.1 description
• trainer_search_study_sources: Performs vector-weighted search specifically for the Agent Trainer curriculum Page 5.2 description

Schema Dashboard Data Flow

Title: Schema Dashboard Live Update Flow

Sources: docs/CurrentState.md7-10 client/src/App.tsx160

The Migration Spine

The schema evolves through sequential SQL files located in supabase/migrations/. A Python utility, run_migration.py, is used to apply these updates docs/gestaltview-v2.manifest.md11

Critical Migration Milestones

Sources: supabase/migrations/20260311162044_new-migration.sql1-4 supabase/migrations/20260420150000_human_continuity_schema.sql1-8 docs/CurrentState.md8

Security & RLS Policies

Row Level Security (RLS) is strictly enforced to ensure that users can only access their own data, while DIs have restricted access to shared knowledge fragments.

• User Isolation: Tables like bucket_drops and consciousness_profiles are partitioned by user_id or auth.uid() supabase/migrations/20260311162044_new-migration.sql17-25
• Admin Access: The /schema-dashboard and certain embodiment sync scripts require an admin role or a valid gv_admin_session cookie docs/CurrentState.md7-22
• Cron Security: Cron jobs (e.g., codex-drain) are protected by verifying the x-vercel-cron-schedule header or a bearer secret docs/CurrentState.md27-32

Data Access Mapping

Title: Natural Language Space to Database Entities

Sources: supabase/migrations/20260311162044_new-migration.sql15-103 docs/CurrentState.md59

Embodiment Profile Synchronization

The embodiment system uses a specialized script, scripts/sync-embodiment-profiles.ts, to bridge the local .embodiment.json files with the live Supabase database. This process includes:

1. Normalization: Ensuring readiness_scores are within the 0..1 range docs/CurrentState.md51
2. Upserting: Pushing 24+ core profiles (e.g., billy, art-teacher) into the embodiment_profiles table docs/CurrentState.md58-60
3. Registry Generation: Updating shared/embodiment/generated.ts to reflect the current database state docs/CurrentState.md61

Sources: docs/CurrentState.md45-62 scripts/sync-embodiment-profiles.ts

Source MHT: Authentication & Session Management _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7.2-authentication-and-session-management \ Mermaid diagrams restored: 2

GestaltView v2 employs a hybrid authentication architecture designed to bridge the gap between browser-native Supabase Auth and a secure, server-side session management system for administrative and high-tier operations. This system ensures cognitive justice by protecting user data while providing seamless access across the platform's five rooms.

Hybrid Authentication Architecture

The system operates on two primary layers:

1. Browser Layer (Supabase Auth): Handles Google OAuth, Magic Links, and Email/Password flows directly in the client client/src/lib/supabaseAuth.ts28-34
2. Server Layer (GV Admin Session): A custom, HMAC-signed session cookie (gv_admin_session) that mirrors or upgrades the Supabase session for secure API access api/_lib/auth.ts6-12

Authentication Flow Diagram

This diagram illustrates the bridge between the client-side Supabase Auth and the server-side session synchronization.

Sources: client/src/pages/AuthCallback.tsx25-31 client/src/lib/supabaseAuth.ts176-206 api/_lib/auth.ts221-252

Tiered Verification & User Tiers

The system categorizes users into five distinct tiers, which dictate feature availability and rate limits client/src/contexts/AuthContext.tsx11

getAuthUser() Logic

The server-side getAuthUser() function performs tiered verification:

1. Cookie Check: Attempts to verify the gv_admin_session cookie using verifySessionToken() api/_lib/auth.ts176-219
2. Signature Validation: Uses SESSION_SECRET and crypto.timingSafeEqual to prevent timing attacks and tampering api/_lib/auth.ts90-96 api/_lib/auth.ts191-192
3. Cache Fallback: Utilizes AUTH_PROFILE_CACHE for performance during high-frequency requests.

Administrative Access Control

Administrative and Founder privileges are strictly controlled via environment-variable allowlists and specialized middleware.

Key Security Entities

Sources: api/_lib/auth.ts47-50 api/_lib/auth.ts137-142 api/_lib/auth.ts224-225

Session State & Rate Limiting

The AuthProvider maintains a PublicSessionState for all users, including anonymous ones, to track usage metrics like billyQueryCount client/src/contexts/AuthContext.tsx64-70

Rate Limit Data Flow

The system tracks query counts via the /api/session/state endpoint client/src/contexts/AuthContext.tsx112-128

Sources: client/src/contexts/AuthContext.tsx138-142 client/src/contexts/AuthContext.tsx72-78

Implementation Details

The AuthCallback Bridge

The AuthCallback component acts as the critical synchronization point when a user returns from an OAuth provider or Magic Link.

1. Token Extraction: It reads PKCE code or implicit access_token from the URL client/src/lib/supabaseAuth.ts44-61
2. Session Establishment: Calls establishBrowserSessionFromCallbackUrl() to finalize the Supabase session client/src/lib/supabaseAuth.ts63-93
3. Cookie Sync: Invokes syncBrowserSessionToAppCookie() which hits /api/auth/supabase/session to set the server-side gv_admin_session cookie client/src/lib/supabaseAuth.ts176-206

Environment Variables

The system relies on several critical variables defined in .env.example:

• SESSION_SECRET: Used for signing the admin session HMAC .env.example23
• FOUNDER_ADMIN_EMAILS: Comma-separated list of emails with superuser access .env.example19
• ADMIN_PASSWORD_HASH: Scrypt/PBKDF2 hash for legacy admin password login .env.example21
• VITE_SUPABASE_URL & VITE_SUPABASE_ANON_KEY: Public keys for browser-side Supabase SDK .env.example27-28

Sources: client/src/pages/AuthCallback.tsx10-31 docs/VERCEL_ENV_CHECKLIST.md40-51

Source MHT: Vercel Deployment & Cron Jobs _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7.3-vercel-deployment-and-cron-jobs \ Mermaid diagrams restored: 2

This page details the configuration and operational logic for the GestaltView v2 backend on Vercel. It covers the serverless function architecture, the routing layer, and the four critical cron-driven background processes that maintain the system's "metabolism"—draining job queues, upgrading provenance records, and maintaining consciousness profile portraits.

1. Vercel Configuration (vercel.json)

The vercel.json file serves as the orchestration manifest for the deployment. It defines the build pipeline, the serverless function boundaries, and the HTTP rewrite rules that bridge the frontend SPA with the backend API.

1.1 Function Includes and Rewrites

To maintain a lean deployment while ensuring all necessary dependencies are available to serverless handlers, the configuration uses includeFiles to bundle the shared library api/_lib/** with nearly every endpoint vercel.json:L24-L82.

The rewrites section handles two primary tasks:

1. API Routing: Maps clean REST-like paths (e.g., /api/gate/orders/:id) to specific internal handlers like /api/gate/order?id=$1 vercel.json:L83-L116.
2. SPA Fallback: Ensures that any request not matching a static file or an API route is served by index.html, allowing client-side routing (Wouter) to take over vercel.json:L120-L123.

1.2 Cron Schedule Definitions

The system defines four recurring jobs with specific cadences:

Sources: vercel.json:L6-L23, vercel.json:L83-L124.

2. Security & Idempotency Patterns

All cron handlers implement a shared security and reliability contract to prevent unauthorized execution and data corruption.

2.1 isAuthorizedCronRequest

Handlers verify requests using the isAuthorizedCronRequest (or isAuthorized) helper. It checks for:

1. The x-vercel-cron: 1 header sent by Vercel's internal scheduler api/cron/codex-drain.ts:L44.
2. A valid Bearer token matching the CRON_SECRET environment variable for manual triggers api/cron/codex-drain.ts:L51.
3. Bypass if NODE_ENV is not production (local development) api/cron/codex-drain.ts:L53.

2.2 Claim-and-Process Pattern

To prevent race conditions where multiple function instances process the same job, the system uses a "claim" pattern via Supabase RPCs:

1. Fetch & Lock: The handler calls a stored procedure (e.g., claim_codex_jobs or claim_portrait_queue_job) that selects pending rows and atomically marks them as running api/cron/codex-drain.ts:L59-L69, api/cron/profile-portrait-drain.ts:L111-L120.
2. Time-Bound Execution: Handlers track their elapsed time against a MAX_DURATION_MS (usually 50s) to exit gracefully before Vercel's 60s timeout api/cron/codex-drain.ts:L33, api/cron/profile-portrait-drain.ts:L22.

Sources: api/cron/codex-drain.ts:L43-L54, api/cron/profile-portrait-drain.ts:L100-L110.

3. The Four Cron Handlers

3.1 Codex Drain (codex-drain.ts)

This job is the "fallback path" for the GenEngine. It finds pending rows in the codex_jobs table and invokes runCodexExportJob() api/cron/codex-drain.ts:L5-L8.

• Data Flow: Fetches artifact data → Renders HTML/JSON templates → Uploads to CODEX_EXPORT_BUCKET api/cron/codex-drain.ts:L10-L14.
• Idempotency: Storage uploads use upsert: false to ensure a second write fails rather than corrupting data api/cron/codex-drain.ts:L16-L20.

3.2 Profile Portrait Drain (profile-portrait-drain.ts)

Processes the portrait_inference_queue. It is responsible for the transition from raw user signals (bucket drops, memory entries) to a structured "Consciousness Profile" api/cron/profile-portrait-drain.ts:L1-L5.

• Threshold Check: Only proceeds if the user has at least 15 total signals and at least 1 "Bucket Drop" api/cron/profile-portrait-drain.ts:L170-L171.
• Inference: Calls loadProfilePortraitForUser which uses the LLM to synthesize the portrait api/cron/profile-portrait-drain.ts:L201-L207.

3.3 Profile Portrait Cadence (profile-portrait-cadence.ts)

A monthly maintenance job that identifies users whose latest portrait is older than the first of the current month api/cron/profile-portrait-cadence.ts:L58-L60. It enqueues a new inference job with priority 1 api/cron/profile-portrait-cadence.ts:L91-L94.

3.4 Provenance Upgrade (provenance-upgrade.ts)

Ensures the long-term integrity of the "Diligence" system by upgrading OpenTimestamps receipts.

• Logic: Finds provenance_envelopes with ots_status='pending' older than 90 minutes api/cron/provenance-upgrade.ts:L5-L7.
• Integration: Attempts to upgrade the .ots file via Bitcoin block attestation by contacting OTS calendars (e.g., Alice, Bob, Finney) api/cron/provenance-upgrade.ts:L18-L22.
• Outcome: If successful, it updates the envelope with a bitcoin_attestation and sets the status to upgraded api/cron/provenance-upgrade.ts:L180-L200.

Sources: api/cron/codex-drain.ts:L1-L27, api/cron/profile-portrait-drain.ts:L1-L42, api/cron/profile-portrait-cadence.ts:L1-L21, api/cron/provenance-upgrade.ts:L1-L11.

4. System Diagrams

Diagram 1: Natural Language to Cron Code Mapping

This diagram maps the high-level operational requirements to the specific code entities that implement them.

Sources: api/cron/codex-drain.ts:L30, api/cron/profile-portrait-drain.ts:L9, api/cron/provenance-upgrade.ts:L102, api/cron/profile-portrait-cadence.ts:L91.

Diagram 2: Portrait Inference Data Flow

Visualizes the transition from user evidence to a persisted portrait artifact.

Sources: api/cron/profile-portrait-drain.ts:L111-L213, api/cron/profile-portrait-drain.ts:L164-L171.

5. Deployment Checklist Summary

The deployment relies on a specific set of environment variables to function. Missing variables will cause cron jobs to fail or degrade to "offline-fallback" modes.

Sources: docs/VERCEL_ENV_CHECKLIST.md:L7-L26, api/cron/provenance-upgrade.ts:L24.

Source MHT: Supabase Edge Functions _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7.4-supabase-edge-functions \ Mermaid diagrams restored: 2

Supabase Edge Functions in GestaltView v2 are Deno-based serverless functions used for high-frequency runtime event capture, batch data ingestion, and background maintenance tasks. These functions operate outside the main Vercel deployment to provide low-latency processing and direct interaction with the Supabase database and storage layers.

Shared Utilities (_shared/)

The Edge Functions rely on a set of shared utility modules located in the supabase/functions/_shared/ directory to standardize authentication, response formatting, and database access.

Sources: docs/gestaltview-v2.manifest.md:24-40, docs/CurrentState.md:68-87

Core Edge Functions

gsvw-capture-event

This function is the primary entry point for capturing runtime telemetry and user interaction events. It is designed to be called directly from the client application.

• Authentication: Requires a valid project JWT or service-role authorization path docs/CurrentState.md77-78
• Data Flow: Receives event payloads and writes them directly to the gsvw_runtime_capture_events table docs/CurrentState.md83-86

gsvw-ingest-batch

Handles the bulk ingestion of documents and knowledge fragments. This function is typically invoked by the gestaltview_manifest_pipeline.py or GitHub Actions during corpus updates.

• Security: Protected by the GESTALTVIEW_INGEST_SECRET environment variable docs/CurrentState.md73-76
• Operation: Supports a dry_run mode to simulate document writes without committing to the database docs/CurrentState.md85

gsvw-dormancy-review

A maintenance function that identifies inactive or "dormant" profiles and artifacts based on the Constitutional Invariants regarding data preservation.

• Logic: Scans for candidates that meet dormancy criteria and logs them for review docs/CurrentState.md84

gsvw-runtime-health

Provides a diagnostic snapshot of the Supabase infrastructure, including live table counts and vector index status.

• Output: Returns ok: true and a snapshot of system health, including row counts for capture events docs/CurrentState.md83

corpus-harvest-worker

Automates the harvesting of new data from the knowledge_fragments and skill_fragments tables to ensure the Digital Intelligence (DI) has the most recent context.

Sources: docs/CurrentState.md:68-100, docs/gestaltview-v2.manifest.json:80-97

System Integration Diagram

The following diagram illustrates how Edge Functions bridge the gap between the Client Space and the Database Space.

Data Ingestion and Event Capture Flow

Sources: docs/CurrentState.md:73-87, supabase/migrations/20260420150000_human_continuity_schema.sql:10-34

Deployment and Security Configuration

Edge Functions are deployed using the Supabase CLI. The security model distinguishes between client-facing and operator-only functions.

Code Entity Association

The following diagram maps the logical system names to their specific file entities in the codebase.

Sources: docs/CurrentState.md:93-100, docs/gestaltview-v2.manifest.md:24-40

Source MHT: Prisma ORM & Data Access Layer _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/7.5-prisma-orm-and-data-access-layer \ Mermaid diagrams restored: 1

The Data Access Layer (DAL) in GestaltView v2 provides a structured, type-safe interface for interacting with the Supabase PostgreSQL backend. While the system utilizes a hybrid approach—combining direct Supabase REST/RPC calls for edge functions and real-time features—the Prisma ORM serves as the primary tool for schema management, migrations, and complex relational queries within the Node.js/Vercel serverless environment.

Architecture & Client Initialization

The application uses the @prisma/client package to interact with the database. The client is initialized in a centralized location to ensure connection pooling efficiency and type consistency across the API routes.

Database Client (db.ts)

The db.ts client is the singleton entry point for all Prisma operations. It leverages the DATABASE_URL environment variable for connectivity. During development and CI, the prisma:verify script is used to ensure the live database schema matches the expectations of the Prisma client by executing a SQL check against specific columns.

Hybrid Coexistence

GestaltView employs a "Two-Path" data strategy:

1. Prisma Path: Used for structured business logic, identity management, and relational mutations (e.g., AppUsers, Workspaces).
2. Supabase REST Path: Used in api/_lib/supabase.ts for zero-dependency interactions, specialized vector searches (using the vector extension), and high-throughput ingestion pipelines.

Data Flow Diagram: Multi-Path Access

This diagram illustrates how the system routes requests through Prisma versus the direct Supabase client.

"Data Access Flow"

Sources: package.json:41-41 (), api/_lib/supabase.ts:1-21 (), package.json:61-66 ()

Prisma Schema & Core Models

The schema.prisma file defines the source of truth for the application's data structures. It is organized into domain groups that reflect the "Five-Room" architecture and the Digital Intelligence (DI) governance model.

Key Models

Model Association Diagram

This diagram maps the high-level system concepts to the specific Prisma models and database entities.

"Natural Language to Code Entity Mapping"

Sources: api/_lib/supabase.ts:206-223 (), api/_lib/supabase.ts:260-271 (), docs/20260420_schema_delta.md:28-50 (), client/src/components/workspaces-interface.tsx:13-21 ()

Migration Structure & SQL Integration

Migrations are managed via the prisma/migrations/ directory, following a strict "Migration Spine" protocol.

Migration Lifecycle

1. Deployment: Handled via prisma migrate deploy in CI/CD pipelines.
2. Manual Overrides: The system frequently uses raw SQL migrations (e.g., 20260420150000_human_continuity_schema.sql) to handle PostgreSQL-specific features that Prisma may not fully support, such as the vector extension, pg_trgm, and complex Row Level Security (RLS) policies.
3. Verification: The prisma:verify script executes prisma/verification/verify_expected_columns.sql to ensure the underlying Supabase tables haven't drifted from the expected application schema.

Schema Deltas

Recent schema evolutions have focused on the "Human Continuity" layer, adding specialized tables for:

• human_identity_profiles
• human_cognition_profiles
• human_memory_records
• context_injection_rules

Sources: package.json:37-41 (), supabase/migrations/20260420150000_human_continuity_schema.sql:10-12 (), docs/20260420_schema_delta.md:8-24 ()

Data Access Patterns

Type-Safe Ingestion

The ingestion pipeline uses MemoryEntryUpsert and MemoryEntryUpdate interfaces to ensure that data entering the system via the ingest_corpus.py script or Edge Functions adheres to the required structure, including content_hash for deduplication and importance for retrieval ranking.

Workspace & Document Management

Workspace operations are encapsulated in the WorkspacesInterface, which handles the synchronization between local browser state (localStorage) and the remote Supabase/Prisma store.

"Workspace Persistence Pattern"

Seeding

The system provides two seeding mechanisms:

1. Prisma Seed: node --import tsx prisma/seed.ts for structural application data.
2. Knowledge Seed: python3 scripts/seed_billy_knowledge.py for populating the vector store with the core Billy personality and knowledge fragments.

Sources: api/_lib/supabase.ts:120-152 (), client/src/components/workspaces-interface.tsx:31-46 (), package.json:35-36 ()

Source MHT: Inner World & Memory Persistence _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/8-inner-world-and-memory-persistence \ Mermaid diagrams restored: 2

The Dynamic Inner World (also known as the "Museum of You") is the primary space for reflection, synthesis, and long-term memory visualization in GestaltView docs/ROOM_DEFINITIONS.md32 It represents the third mode of being: Distilled / Reflective docs/ROOM_DEFINITIONS.md16 Unlike the Blackboard Room (active work) or the External Scaffold (structural accumulation), the Inner World focuses on what the accumulated data means docs/ROOM_DEFINITIONS.md19-21

System Overview & Causal Flow

The Inner World operates at the end of the system's causal pipeline. Active work performed in other rooms emits events to the Scaffold, which the Inner World then reads to synthesize museum-grade exhibits docs/ROOM_DEFINITIONS.md18-22

Causal Pipeline Diagram

Sources: docs/ROOM_DEFINITIONS.md18-22 client/src/lib/innerWorldFiles.ts86-90 api/inner-world/artifacts.ts87-106

InnerWorldArtifact Lifecycle

An InnerWorldArtifact is a self-contained interactive object (typically HTML) that serves as a "first-class museum object" docs/ROOM_DEFINITIONS.md69

Artifacts are defined by the InnerWorldArtifactRecord type client/src/lib/innerWorldFiles.ts35-50 They are rendered using the HtmlArtifactRenderer which utilizes an iframe-based sandbox for security and visual isolation client/src/components/inner-world/InnerWorldArtifactGallery.tsx5 client/src/components/inner-world/InnerWorldArtifactGallery.tsx97-106

For details on the 3D spatial distribution and the "Golden Angle" algorithm, see Inner World Artifact Gallery & Spatial Renderer.

File Management & Persistence

The system employs a multi-stage persistence pipeline to ensure memory continuity.

1. Local State: Managed via innerWorldFiles.ts, utilizing localStorage keys like gestaltview.innerWorldArtifacts.v1 client/src/lib/innerWorldFiles.ts88
2. Tombstoning: To prevent deleted items from being resurrected during server merges, a DELETED_ARTIFACT_IDS_KEY stores "tombstones" of permanently removed IDs client/src/lib/innerWorldFiles.ts96
3. Remote Persistence: The api/inner-world/artifacts.ts handler manages CRUD operations against the Supabase inner_world_artifacts table api/inner-world/artifacts.ts40-41
4. Binary Storage: Files (PDFs, Images, Audio) are stored in Supabase Storage buckets via the uploadInnerWorldFileObject utility api/_lib/inner-world.ts110-133

For details on file kind detection and signed URL generation, see File Management & Storage.

Session Recap System

The Session Recap is a specialized synthesis process triggered within the Blackboard Room docs/ROOM_DEFINITIONS.md68

Recap Generation Logic

Sources: docs/ROOM_DEFINITIONS.md69-70 client/src/lib/blackboardRecapArtifacts.ts17-50

The SessionRecapGenerator produces artifacts with a "Neural Aurora" aesthetic, requiring four sections: What we built, What emerged, What's still in motion, and Worth holding docs/ROOM_DEFINITIONS.md77

For details on the UniversalCaptureBar and capture routing, see Session Recap & Capture Routing.

Child Pages

• Inner World Artifact Gallery & Spatial Renderer — Details on the DynamicWorldSpaceRenderer, ExhibitPod, and spatial distribution.
• File Management & Storage — Technical deep dive into innerWorldFiles.ts, Supabase Storage integration, and the merge loop.
• Session Recap & Capture Routing — In-depth look at the SessionRecapGenerator, captureRouting.ts, and the Bucket Drop mechanism.

Sources:

• docs/ROOM_DEFINITIONS.md1-120
• client/src/lib/innerWorldFiles.ts1-115
• api/inner-world/artifacts.ts1-121
• client/src/lib/blackboardRecapArtifacts.ts1-60
• api/_lib/inner-world.ts1-189
• client/src/components/inner-world/InnerWorldArtifactGallery.tsx1-108

Source MHT: Inner World Artifact Gallery & Spatial Renderer _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/8.1-inner-world-artifact-gallery-and-spatial-renderer \ Mermaid diagrams restored: 2

The Dynamic Inner World (Museum of You) serves as the system's distilled, reflective mode. It synthesizes active work and accumulated structural data into high-fidelity, interactive exhibits. Unlike the raw capture of the Blackboard Room or the structural map of the External Scaffold, the Inner World focuses on curated presentation and long-term resonance docs/ROOM_DEFINITIONS.md8-21

Spatial Rendering Architecture

The Inner World utilizes a spatial rendering pipeline that transitions between 2D gallery views and a 3D "Museum Hall" experience. The DynamicWorldSpaceRenderer serves as the primary orchestrator for this environment client/src/features/dynamic-inner-world/world-renderer/DynamicWorldSpaceRenderer.tsx53-78

The World Plan & Golden Angle Distribution

Spatial layout is governed by buildWorldPlan, which transforms raw artifact data into a geometric arrangement for the 3D stage client/src/features/dynamic-inner-world/world-renderer/buildWorldPlan.ts

To prevent visual overlap and create a natural "constellation" effect, the system employs a Golden Angle distribution algorithm. This ensures that artifacts (Exhibits) are spaced according to phyllotaxis patterns, maximizing aesthetic density without clutter.

Rendering Components

Sources: client/src/features/dynamic-inner-world/world-renderer/DynamicWorldSpaceRenderer.tsx1-179 docs/ROOM_DEFINITIONS.md120-135

Artifact Pipeline: From Capture to Exhibit

Artifacts enter the Inner World through a defined lifecycle, often originating as Session Recaps from the Blackboard Room docs/ROOM_DEFINITIONS.md68-78

Data Flow: Natural Language to Code Entities

The following diagram bridges the conceptual "Museum Exhibit" to the underlying code structures and API handlers.

Inner World Data Flow

Sources: client/src/lib/blackboardRecapArtifacts.ts17-50 api/inner-world/artifacts.ts87-106 client/src/features/dynamic-inner-world/world-renderer/DynamicWorldSpaceRenderer.tsx80-93

Artifact Schema

The InnerWorldArtifactRecord is the core data contract for the gallery client/src/lib/innerWorldFiles.ts35-50:

• id: Unique identifier (often prefixed gv-).
• html: The full self-contained HTML content of the artifact.
• evidenceNodeIds: UUIDs of the raw Scaffold nodes that informed this synthesis.
• status: queued, rendering, ready, failed, draft, active, or archived.
• originRoom: Tracks whether the artifact came from blackboard, creation_corner, etc.

Rendering & Interaction

HtmlArtifactRenderer

The HtmlArtifactRenderer is an iframe-based component used to safely render untrusted or complex HTML artifacts client/src/lib/rendering/renderers/HtmlArtifactRenderer.tsx It is used both in the 2D InnerWorldArtifactGallery client/src/components/inner-world/InnerWorldArtifactGallery.tsx97-105 and the full-screen ArtifactExpandView client/src/components/ArtifactExpandView.tsx150-157

Curator Console & Evidence Connections

The CuratorConsole provides the UI for managing the museum state, while Evidence Connections allow users to discover the relationship between a synthesized artifact and its source data client/src/features/dynamic-inner-world/world-renderer/components/CuratorConsole.tsx

• ResonanceRail: A UI element that visualizes "links" between artifacts based on shared tags or PLK (Private Language Key) resonance client/src/features/dynamic-inner-world/world-renderer/components/ResonanceRail.tsx
• Discovery: Users can click "Inspect" to view the evidenceNodeIds in the InnerWorldInspector client/src/components/inner-world/InnerWorldInspector.tsx13-19

Persistence & Storage

Inner World data is persisted via a multi-stage pipeline to ensure low latency and durability.

Persistence Logic Association

Sources: client/src/lib/innerWorldFiles.ts134-144 api/inner-world/artifacts.ts87-106 api/_lib/inner-world.ts110-133

Key Persistence Functions

• appendInnerWorldArtifact: Adds a record to local storage and triggers a sync event client/src/lib/innerWorldFiles.ts257-260
• uploadInnerWorldFileObject: Handles the transfer of binary assets or large HTML blobs to Supabase Storage api/_lib/inner-world.ts110-115
• createInnerWorldSignedUrl: Generates time-limited access tokens for private artifact assets api/_lib/inner-world.ts145-155
• Tombstone Mechanism: The system uses DELETED_ARTIFACT_IDS_KEY in local storage to prevent the server-merge loop from resurrecting deleted artifacts client/src/lib/innerWorldFiles.ts94-96

Sources: client/src/lib/innerWorldFiles.ts1-115 api/inner-world/artifacts.ts36-54 api/_lib/inner-world.ts1-155

Source MHT: File Management & Storage _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/8.2-file-management-and-storage \ Mermaid diagrams restored: 2

The File Management & Storage subsystem handles the persistence, retrieval, and transformation of user-generated content and Digital Intelligence (DI) outputs. It facilitates a multi-stage persistence pipeline that bridges volatile client-side state with permanent cloud storage.

Multi-Stage Persistence Pipeline

GestaltView utilizes a tiered storage strategy to ensure high availability and offline resilience while maintaining a centralized source of truth.

1. LocalStorage (Volatile/Immediate): Initial capture and local caching of UserFileRecord and InnerWorldArtifactRecord occur in the browser's localStorage client/src/lib/innerWorldFiles.ts117-144
2. Vercel Serverless (Intermediary): API endpoints in api/inner-world/* act as the gateway, handling authentication via requireAuth api/inner-world/artifacts.ts28-32 and data normalization.
3. Supabase Storage & PostgreSQL (Permanent): - Binary Data: Files (images, PDFs, audio) are stored in the user-files Supabase bucket api/_lib/inner-world.ts42-44 - Metadata & HTML: Structured data and rendered artifact HTML are stored in the inner_world_artifacts and user_files PostgreSQL tables api/inner-world/artifacts.ts87-106

Data Flow: File Upload to Persistence

The following diagram illustrates the flow from a user action to permanent storage.

File Ingestion & Storage Flow

Sources: client/src/lib/innerWorldFiles.ts502-550 api/_lib/inner-world.ts110-133 api/inner-world/artifacts.ts87-106

Core Logic: innerWorldFiles.ts

This library is the primary engine for file and artifact lifecycle management.

Key Data Structures

• UserFileRecord: Represents a raw file (PDF, Image, Markdown) with metadata like roomOrigin, storagePath, and kind client/src/lib/innerWorldFiles.ts8-24
• InnerWorldArtifactRecord: Represents a synthesized exhibit (usually HTML) meant for the Dynamic Inner World. It includes evidenceNodeIds to link back to the External Scaffold client/src/lib/innerWorldFiles.ts35-50

Critical Functions

• createUserFileRecord: Initializes a file record, detects its UserFileKind (markdown, html, pdf, etc.), and saves it locally client/src/lib/innerWorldFiles.ts502-536
• pinFileToInnerWorld: Converts a UserFileRecord into an InnerWorldArtifactRecord by generating a standard HTML wrapper client/src/lib/innerWorldFiles.ts672-705
• mergeInnerWorldArtifacts: Synchronizes local state with server data. It utilizes a Tombstone Mechanism via DELETED_ARTIFACT_IDS_KEY to ensure that artifacts deleted by the user are not resurrected during the next server sync client/src/lib/innerWorldFiles.ts94-97 client/src/lib/innerWorldFiles.ts380-410

Sources: client/src/lib/innerWorldFiles.ts1-205 client/src/lib/innerWorldFiles.ts380-410

API & Backend Persistence

The backend provides secure access to the inner_world schema and storage buckets.

Artifacts CRUD (api/inner-world/artifacts.ts)

Handles the persistence of synthesized exhibits. It uses upsert with a onConflict: "source_ref" clause to allow client-side generated IDs to serve as the unique key across syncs api/inner-world/artifacts.ts87-106

Storage Utilities (api/_lib/inner-world.ts)

• Signed URL Generation: Since the user-files bucket is private, the system generates time-limited signed URLs for file previews via createInnerWorldSignedUrl api/_lib/inner-world.ts145-155
• Storage Pathing: Files are organized in the bucket following the pattern: user-files/{userId}/{fileId}/{safeName} api/_lib/inner-world.ts68-76

Artifact Status Lifecycle

The inner_world_artifacts.status column was expanded to support a complex rendering and review pipeline supabase/migrations/20260625174800_widen_inner_world_artifacts_status.sql1-15

Sources: api/inner-world/artifacts.ts87-106 api/_lib/inner-world.ts145-155 supabase/migrations/20260625174800_widen_inner_world_artifacts_status.sql13-15

UI Components

FileExplorer & FilePreviewPane

The FileExplorer provides a "living collection" interface for navigating the user's library client/src/components/files/FileExplorer.tsx92-95

• Filtering: Supports filtering by FileRoomOrigin (Blackboard, Creation Corner, etc.) and UserFileKind client/src/components/files/FileExplorer.tsx37-39
• Preview: FilePreviewPane renders the file content using FilePreview and provides action buttons like "Pin to Inner World" or "Open in Blackboard Room" client/src/components/files/FilePreviewPane.tsx96-115

InnerWorldArtifactGallery

Renders InnerWorldArtifactRecord objects as interactive exhibits.

• Renderer: Uses HtmlArtifactRenderer to display the artifact's HTML in a sandboxed iframe client/src/components/inner-world/InnerWorldArtifactGallery.tsx97-106
• Metadata Display: Shows the origin room, curator DI, and associated evidence nodes client/src/components/inner-world/InnerWorldArtifactGallery.tsx54-85

Sources: client/src/components/files/FileExplorer.tsx1-100 client/src/components/files/FilePreviewPane.tsx1-140 client/src/components/inner-world/InnerWorldArtifactGallery.tsx1-107

Integration: Session Recaps & Creation Corner

Artifacts are rarely created manually; they are usually outputs of other rooms.

Blackboard Room Recaps

When a session ends, the SessionRecapGenerator creates a RecapArtifact. This is transformed into an InnerWorldArtifactRecord via buildBlackboardRecapInnerWorldArtifact client/src/lib/blackboardRecapArtifacts.ts17-50

• Default Status: Recaps are initialized with status: "queued", requiring a user action to "publish" them to the museum client/src/lib/blackboardRecapArtifacts.ts48

Creation Corner Blueprints

Outputs from the Creation Corner (Blueprints, Code, etc.) are wrapped in a Neural Aurora themed HTML shell using buildCreationCornerHtml client/src/lib/creationCornerArtifacts.ts76-89 before being saved to the Inner World.

Artifact Generation & Persistence Logic

Sources: client/src/lib/blackboardRecapArtifacts.ts17-59 client/src/lib/creationCornerArtifacts.ts128-158 client/src/lib/innerWorldFiles.ts86-90

Source MHT: Session Recap & Capture Routing _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/8.3-session-recap-and-capture-routing \ Mermaid diagrams restored: 2

This section details the mechanisms for synthesizing session experiences into structured artifacts and the routing logic that governs how raw captures (thoughts, files, voice) move from the Blackboard Room into the External Scaffold or the Dynamic Inner World.

1. Session Recap System

The Session Recap system is responsible for transforming a user's active session—comprising raw captures and conversation history—into a characterful, interactive HTML artifact. This process is orchestrated by the SessionRecapGenerator component and executed via a specialized LLM cascade.

1.1 SessionRecapGenerator

The SessionRecapGenerator is a client-side component that aggregates session data and manages the generation lifecycle client/src/components/SessionRecapGenerator.tsx5-16

• State Management: It tracks the generation status (idle, generating, done, error) and caches the resulting artifact in sessionStorage using a slugified key to prevent loss on page refresh client/src/components/SessionRecapGenerator.tsx135-171
• Orchestration: It calls requestOrchestrationDecision to summarize the session before invoking the recap API client/src/components/SessionRecapGenerator.tsx229-234
• Output: Generates a RecapArtifact with status: "draft". This ensures recaps do not automatically clutter the Dynamic Inner World until the user explicitly promotes them client/src/components/SessionRecapGenerator.tsx104-124

1.2 The /api/sessionRecap Route

The backend handler manages the LLM request and enforces a strict "HTML Gate" to ensure the output is valid and renderable.

• Voice Normalization: The system supports multiple DI personas (Billy, Architect, Curator) for the recap's tone shared/sessionRecap.ts31-48 The normalizeRecapVoice function defaults to recap-di if an invalid ID is provided shared/sessionRecap.ts58-65
• Retry Logic & Validation: The handler attempts up to two LLM calls. If the first fails the validateRecapHtml check, a second attempt is made with a repair note api/sessionRecap.ts53-72
• Fallback Mechanism: If the LLM fails to produce valid HTML after two tries, buildRecapFallbackHtml generates a deterministic, template-based recap to ensure the user always receives a result api/sessionRecap.ts75-84

1.3 Recap Voice Profiles

Sources: shared/sessionRecap.ts31-48 api/sessionRecap.ts42-45

2. Capture Routing & Storage

Capture routing defines the "Capture Lane" where raw inputs are transformed into CaptureOrb entities and dispatched to various storage surfaces.

2.1 UniversalCaptureBar

The UniversalCaptureBar is the primary entry point for raw data. It supports:

• Text: Standard textarea input.
• Voice: Utilizes the browser's SpeechRecognition API (if enabled in UserSurfaceSettings) to stream interim and final transcripts client/src/components/capture/UniversalCaptureBar.tsx57-115
• Files: Managed via a hidden file input triggered by Cmd/Ctrl+U or a UI button client/src/components/capture/UniversalCaptureBar.tsx143-163

2.2 Scaffold Storage Lifecycle

The scaffoldStorage utility (and captureRouting.ts exports) manages the transition of orbs between different states client/src/lib/scaffoldStorage.ts184-201:

1. Pending: Orbs waiting in the ScaffoldQueue.
2. Approved: Orbs promoted to the External Scaffold.
3. Archived: Orbs moved to ARCHIVED_SCAFFOLD_ORBS_KEY to clear the active view while retaining metadata client/src/lib/scaffoldStorage.ts22-24
4. Inner World: High-resonance artifacts promoted to the permanent gallery.

2.3 Bucket Drops

The Bucket Drop mechanism is a "zero-friction" capture system designed for long-term storage or delayed release.

• Sealing: Users can "seal" a drop with a release trigger (date or event) client/src/components/BucketDrops.tsx33-37
• Server Sync: Drops are persisted to the server via createBucketDropOnServer and hydrated on the client through mergeBucketDropOrbs client/src/components/BucketDrops.tsx89-103
• Orb Conversion: Every drop is converted to a CaptureOrb with origin: "bucket_drop" to maintain compatibility with the room architecture client/src/components/BucketDrops.tsx53-75

3. Data Flow Diagrams

3.1 Session Recap Generation Flow

This diagram maps the transition from client-side interaction to the LLM Router and back to the Artifact Gallery.

Sources: client/src/components/SessionRecapGenerator.tsx189-245 api/sessionRecap.ts31-115 shared/sessionRecap.ts222-230

3.2 Capture Routing Architecture

Mapping the flow from raw input to persisted CaptureOrb states.

Sources: client/src/lib/captureRouting.ts1-86 client/src/lib/scaffoldStorage.ts122-151 client/src/components/BucketDrops.tsx112-135

4. Download & Sanitization

The system provides specialized utilities for exporting session data while maintaining security.

4.1 Session Recap Downloads

The sessionRecapDownloads.ts module handles the transformation of a RecapArtifact into various formats:

• HTML: Sanitized to remove sensitive scripts or localStorage calls client/src/lib/sessionRecapDownloads.ts173-174
• Markdown/TXT: Strips HTML tags and formats metadata for readability shared/sessionRecap.ts103-105
• JSON: Exports the raw artifact and metadata client/src/tests/session-recap-download.test.ts57-60

4.2 Sanitization Logic

sanitizeRecapHtmlForDownload performs the following safety transforms client/src/tests/session-recap-download.test.ts7-28:

• Replaces localStorage.setItem with a safe, disabled reference.
• Rewrites internal app actions (e.g., "Return to Blackboard") into absolute URLs pointing back to the platform.
• Disables platform-specific interactive buttons that require a live session context.

Sources: client/src/lib/sessionRecapDownloads.ts34-36 client/src/tests/session-recap-download.test.ts7-28 shared/sessionRecap.ts103-105

Source MHT: GATE Commerce & Packaging System _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/9-gate-commerce-and-packaging-system \ Mermaid diagrams restored: 2

The GATE (Gestaltview Automated Technical Export) system is the commercial engine of GestaltView. it enables the packaging, sale, and deployment of Digital Intelligence (DI) behavioral frameworks and runtime scaffolds. It manages the transition from a conceptual draft to a physical artifact (ZIP package) through a structured lifecycle integrated with Stripe for billing and Supabase for state persistence.

System Overview

The GATE system bridges the gap between the DI training environment and a deliverable product. It allows users to define "Drafts" of a DI system, purchase them via tiered subscriptions or flat-fee orders, and trigger a build pipeline that assembles a white-label version of the GestaltView runtime.

Commercial Tiers

The system defines four primary tiers for the hosted runtime and packaging:

• SOLO_SPARK (Solo Founder): Hosted access for individual builders client/src/pages/AgentTrainerPricing.tsx90-110
• STUDIO (Small Team): Collaborative curation and shared workspaces client/src/pages/AgentTrainerPricing.tsx112-132
• GROWTH (Scaling Business): Governance, audit logging, and private deployment paths client/src/pages/AgentTrainerPricing.tsx134-154
• ENTERPRISE: White-label Billy deployment with custom PLK training client/src/pages/Pricing.tsx94-112

The Package Lifecycle

The system follows a strict state machine to ensure consistency between payment and delivery:

1. Draft: User configures package parameters in the GATEPackageBuilderPage.
2. Checkout: Stripe session is created via api/stripe/checkout.ts.
3. Order: Upon successful webhook, a record is created in gate_orders.
4. Build: A gate_build_jobs entry is claimed by the worker to assemble the artifact.
5. Redeem: The user downloads the final ZIP artifact via api/gate/order-redeem.

Logic Flow: Order to Artifact

Sources: vercel.json83-115 client/src/pages/AgentTrainerPricing.tsx88-155 supabase/GestaltView_Schema_Alignment_Reference.md25

GATE Package Builder

The GATEPackageBuilderPage serves as the primary interface for users to customize their DI export. It utilizes the GateSidekick AI assistant to help users refine their PackageConfigDraft.

• Draft Validation: The UI interacts with /api/gate/draft-validate to ensure configurations meet tier-specific constraints vercel.json85-87
• Tier Mapping: Features are toggled based on the selected commercial tier (e.g., Solo vs. Studio) client/src/pages/AgentTrainerPricing.tsx88-155
• Order Tracking: Once a build is initiated, users are redirected to the GATEOrderStatusPage to monitor the gate_build_jobs progress vercel.json101-103

Sources: client/src/pages/GATEPackageBuilderPage.tsx vercel.json83-115

Stripe Integration & Billing

The billing system manages both recurring subscriptions for the hosted platform and one-time payments for GATE packages.

• Checkout Sessions: The api/stripe/checkout.ts handler creates Stripe Checkout sessions, mapping internal Plan IDs (Core, Pro, Enterprise) to Stripe Price IDs client/src/pages/Pricing.tsx42-113
• Webhooks: The api/gate/webhook-stripe endpoint handles asynchronous payment confirmations, updating user tiers and initiating GATE orders vercel.json113-115
• Tier Enforcement: User access to features like SymbioCoder or Diligence exports is determined by the tier column in the users table client/src/pages/Pricing.tsx71-92 supabase/GestaltView_Schema_Alignment_Reference.md46-61

For details on the billing implementation, see Stripe Integration & Billing.

Sources: client/src/pages/Pricing.tsx42-113 api/stripe/checkout.ts supabase/GestaltView_Schema_Alignment_Reference.md46-61

Build Pipeline & Persistence

The backend infrastructure for GATE is built on Supabase, utilizing specialized tables in the commerce_gate domain to track the assembly of ZIP artifacts.

Database Entities

Artifact Generation

The build process is triggered via /api/gate/build-job-run, which executes the composeGatePackageArtifact logic. This process involves:

1. Cloning the white-label scaffold.
2. Injecting the user's specific DI profiles and PLK settings.
3. Bundling the environment into a ZIP archive stored in Supabase Storage.

For details on the build pipeline, see GATE Package Build Pipeline.

Sources: supabase/GestaltView_Schema_Alignment_Reference.md25 vercel.json105-107 scripts/README.md74-91

Code Entity Map

This diagram associates high-level GATE concepts with their specific implementation files and routes.

Sources: vercel.json83-115 supabase/GestaltView_Schema_Alignment_Reference.md25 client/src/pages/AgentTrainerPricing.tsx1-155

Source MHT: GATE Package Build Pipeline _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/9.1-gate-package-build-pipeline \ Mermaid diagrams restored: 2

The GATE (Gestaltview Agent Training & Export) Package Build Pipeline is the automated system responsible for transforming high-level agent configurations and training data into deployable Digital Intelligence (DI) behavioral frameworks. It manages the transition from a conceptual PackageConfigDraft to a finalized gate_artifact through a multi-stage process involving AI-assisted analysis, tier-based validation, and automated build jobs.

Pipeline Architecture & Data Flow

The pipeline operates as a state machine backed by Supabase, moving through drafting, validation, ordering, and execution phases.

High-Level Build Flow

1. Drafting: User defines requirements via GATEPackageBuilderPage, assisted by GateSidekick.
2. Analysis: analyzeGateDraft evaluates the configuration against gateCatalog.ts tier limits.
3. Ordering: Upon checkout, a gate_orders record is created, triggering a gate_build_jobs entry.
4. Execution: build-job-run.ts executes the build, calling composeGatePackageArtifact to synthesize the final bundle.
5. Persistence: Final artifacts are stored in gate_artifacts and linked to the user's account.

System Entity Mapping

The following diagram bridges the Natural Language concepts to the specific Code Entities and Database Tables used in the pipeline.

Diagram: GATE Pipeline Entity Mapping

Sources: vercel.json:85-115, api/cron/codex-drain.ts:5-26

Key Components & Implementation

1. Package Configuration & Analysis

The pipeline begins with the PackageConfigDraft, which defines the scope of the DI (Digital Intelligence).

• GateSidekick: An AI assistant that helps users refine their drafts by suggesting use cases and ensuring compatibility.
• analyzeGateDraft: A function that performs structural validation and ensures the requested features align with the selected tier (SOLO_SPARK, STUDIO, GROWTH, or ENTERPRISE) defined in gateCatalog.ts.

2. The Build Execution (build-job-run.ts)

The build-job-run.ts endpoint is the primary worker for package synthesis. It is typically invoked via a Vercel Cron or a Stripe Webhook post-payment.

Execution Logic:

1. Claiming: Claims a pending job from the gate_build_jobs table.
2. Context Assembly: Gathers TrainingBrief data and EmbodimentProfile fragments.
3. Artifact Composition: Calls composeGatePackageArtifact to generate the Markdown, JSON, and HTML representations of the agent.

3. Repository Layer (Supabase)

The pipeline relies on a set of specialized tables to maintain state and provide an audit trail:

Sources: vercel.json:105-115, api/cron/codex-drain.ts:58-69

Logic Flow: Order to Artifact

The transition from a paid order to a downloadable artifact is handled asynchronously to manage LLM latency and generation time.

Diagram: Build Execution Sequence

Sources: vercel.json:105-115, api/cron/codex-drain.ts:16-26

Tier Definitions & Compatibility

The build pipeline enforces strict constraints based on the gateCatalog.ts definitions.

• SOLO_SPARK: Limited to single-persona exports with basic behavioral hooks.
• STUDIO: Includes multi-persona support and custom PLK (Private Language Key) integration.
• GROWTH: Adds API access and advanced gateUseCases.ts templates.
• ENTERPRISE: Full white-labeling and high-frequency provenance-upgrade support.

gateCompatibility.ts is used during the analyzeGateDraft phase to ensure that selected modules (e.g., Resume Rockstar vs. Musical DNA) do not have conflicting logic within a single package artifact.

Sources: api/cron/codex-drain.ts:71-77, shared/billy/runtime.ts:111-125

Maintenance & Observability

• Keep-Alive: The api/keep-alive.ts endpoint ensures the Supabase connection remains warm to prevent cold-start latency during build jobs api/keep-alive.ts:L1-L12.
• Codex Drain: A companion cron api/cron/codex-drain.ts handles the "lighter first-ship lane" for artifact exports, ensuring the gate_build_jobs queue does not stall api/cron/codex-drain.ts:L1-L8.
• Health Checks: The pipeline status can be monitored via api/billy-health.ts.

Sources: api/keep-alive.ts:142-160, api/cron/codex-drain.ts:12-22

Source MHT: Stripe Integration & Billing _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/9.2-stripe-integration-and-billing \ Mermaid diagrams restored: 2

The Stripe Integration and Billing subsystem manages the commercial lifecycle of GestaltView users, ranging from free-tier exploration to Enterprise-level collaborator provisioning. This system bridges Stripe's checkout and webhook events with the Supabase identity_core and collaboration domains to enforce feature gating and manage user permissions.

Billing Architecture Overview

GestaltView utilizes a tiered subscription model (Core, Pro, Enterprise) to control access to Digital Intelligence (DI) capabilities, memory persistence, and specialized modules like SymbioCoder or Resume Rockstar.

System Data Flow

The following diagram illustrates the flow from a user selecting a plan to the activation of features via Stripe webhooks.

Stripe Checkout & Provisioning Flow

Sources: client/src/pages/Pricing.tsx:142-153, api/stripe/checkout.ts, api/stripe/webhook.ts

Tier Mapping & Feature Gating

User access is governed by the tier column in the public.users table supabase/GestaltView_Schema_Alignment_Reference.md46-61 Feature availability is defined in the Pricing.tsx configuration and enforced through the useAuth hook and BillyProvider.

Defined Tiers

Sources: client/src/pages/Pricing.tsx:35-113, supabase/GestaltView_Schema_Alignment_Reference.md:51-51

Key API Endpoints

Subscription Checkout (api/stripe/checkout.ts)

This endpoint handles the creation of Stripe Checkout sessions. It maps internal planId strings to Stripe Price IDs and configures success/cancel URLs.

Webhook Processing (api/stripe/webhook.ts)

The webhook handler is responsible for:

1. Signature Verification: Validating that requests originate from Stripe using the STRIPE_WEBHOOK_SECRET.
2. Event Dispatching: Handling checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted.
3. Database Sync: Updating the users table with the new tier, subscription_status, and stripe_customer_id supabase/GestaltView_Schema_Alignment_Reference.md52-54

Collaborator Provisioning System

The Collaborator system extends billing into the Enterprise domain, allowing for the creation of governed identities (both human and DI) within a shared workspace.

Provisioning Logic (server/collaborators/provision.ts)

The provisionCollaborator function is the core entry point for creating new entities. It performs the following steps:

1. Duplicate Check: Ensures no existing collaborator is linked to the same agent_id or auth_user_id server/collaborators/provision.ts155-187
2. Key Generation: Creates a unique collaborator_key using a slugified base and a random UUID server/collaborators/provision.ts124-134
3. Row Insertion: Creates records in collaborators, collaborator_roles, and collaborator_embodiment_links server/collaborators/provision.ts189-234

Collaborator Entity Mapping

Sources: server/collaborators/provision.ts:4-45, server/collaborators/provision.ts:189-234

Client-Side Billing Components

Pricing Page (client/src/pages/Pricing.tsx)

The PricingPage provides a visual interface for plan selection. It uses framer-motion for animations and the useAuth hook to determine the user's current subscription state client/src/pages/Pricing.tsx2-4

Upgrade Components

• UpgradeBanner: A contextual UI element that appears when a user hits tier-based limits (e.g., query counts).
• DemoGate: A specialized component used to preview Pro/Enterprise features to Free users, often triggering a redirect to the Pricing page client/src/components/DemoGate.tsx

Administrative & Maintenance Tooling

Collaborator Initialization (scripts/init-collaborator-system.sh)

This bash script verifies the integrity of the collaborator and billing infrastructure. It checks for:

• Presence of required provisioning files scripts/init-collaborator-system.sh121-126
• Wiring of requireAdmin auth wrappers in API routes scripts/init-collaborator-system.sh155-157
• Existence of necessary database tables in the schema snapshot (e.g., collaborators, collaborator_roles) scripts/init-collaborator-system.sh167-173

Billing Helpers (client/src/lib/billing.ts)

A utility module providing readBillingPlanFromSearch and other helpers to parse Stripe redirect parameters and update local application state client/src/pages/Pricing.tsx5

Sources: scripts/init-collaborator-system.sh, server/collaborators/provision.ts, api/collaborators/provision.ts

Source MHT: Data Ingestion, Corpus & Knowledge Pipeline _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/10-data-ingestion-corpus-and-knowledge-pipeline \ Mermaid diagrams restored: 2

The Data Ingestion, Corpus, and Knowledge Pipeline is the backbone of GestaltView’s Digital Intelligence (DI). It transforms raw repository content, documents, and temporal signals into structured, high-dimensional vector embeddings and annotated knowledge fragments. This system ensures that Billy and other agents operate on a grounded, verifiable foundation of truth.

Knowledge Flow Overview

The pipeline operates in three distinct phases: Ingestion, Synthesis, and Diligence. Data is crawled or discovered, chunked into fragments, embedded into a 768-dimensional vector space, and finally annotated with semantic metadata (Loom annotations) to facilitate multi-hop reasoning.

High-Level Ingestion Architecture

Sources: scripts/ingest_corpus.py1-27 scripts/synthesize_corpus.py1-25 scripts/gestaltview_manifest_pipeline.py20-26

10.1. Corpus Ingestion & Knowledge Fragments

The primary entry point for repository knowledge is the ingest_corpus.py script. It performs recursive discovery of files defined in the corpus-map.json and processes them into overlapping chunks to preserve narrative flow.

• Ingestion Engine: scripts/ingest_corpus.py handles text extraction from multiple formats (PDF, Markdown, Source Code) and generates embeddings using models like google/embedding-gecko-300M scripts/ingest_corpus.py72-83
• GIL Protocol: The Gestalt Information Layer (GIL) protocol scripts/gil_protocol.py defines how fragments are ranked and contextually weighted during synthesis.
• Manifest Pipeline: The gestaltview_manifest_pipeline.py provides a production-aligned implementation for batch processing, utilizing exponential backoff and structured logging scripts/gestaltview_manifest_pipeline.py6-18
• Automation: GitHub Actions such as ingest_corpus_v2.yml automate the pipeline, allowing for dry runs, embedding generation via Hugging Face, and direct Supabase synchronization .github/workflows/ingest_corpus_v2.yml1-50

For details, see Corpus Ingestion & Knowledge Fragments.

10.2. Gravity Protocol & Diligence Explorer

The system maintains high-fidelity provenance through the Two-Pass Gravity Protocol. This protocol ensures that every claim made by the DI can be traced back to a specific corpus fragment, preventing "hallucination drift."

• Claim Analysis: The protocol analyzes "load-bearing claims" and detects incentive distortions within ingested data shared/gravity/protocol.ts
• Diligence Infrastructure: The Diligence Explorer UI allows developers to audit the Diligence_Reports/ CSV exports and verify OTS (OpenTimestamps) blockchain anchors for temporal proof.
• Auditing: The gestaltview_crawler.py script performs SEO and accessibility audits, flagging pages where core GestaltView terms are missing from the surface text scripts/gestaltview_crawler.py47-60

For details, see Gravity Protocol & Diligence Explorer.

10.3. Profile Portrait & Consciousness Pipeline

The Consciousness Pipeline transforms raw ingestion signals into a cohesive "Portrait" of a user or entity. This is the mechanism by which the platform achieves "consciousness-serving" continuity.

• Inference Queue: Signals from bucket_drops and knowledge_fragments are collected in the portrait_inference_queue.
• Thresholds: A portrait is only generated once a minimum signal count is reached (typically 15 total signals, including at least one Bucket Drop).
• Temporal Backfill: The temporal_backfill.py script ensures that historical data is correctly timestamped and associated with the evolving profile scripts/temporal_backfill.py
• Artifact Generation: LLM-based runs generate portrait_inference_runs which are eventually persisted as ConsciousnessProfiles for the frontend to display via the ProfileDisplay component.

For details, see Profile Portrait & Consciousness Pipeline.

Data Entity Mapping

This diagram bridges the gap between the conceptual "Knowledge" and the actual database tables used in the gestaltview_manifest_pipeline.py.

Entity Relationship: Ingestion to Retrieval

Sources: scripts/gestaltview_manifest_pipeline.py20-26 scripts/ingest_corpus.py113-134 scripts/synthesize_corpus.py7-11

Source MHT: Corpus Ingestion & Knowledge Fragments _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/10.1-corpus-ingestion-and-knowledge-fragments \ Mermaid diagrams restored: 2

The Corpus Ingestion pipeline is the primary mechanism for transforming raw repository assets, documentation, and external data into structured, semantically searchable Knowledge Fragments. This system bridges the gap between static files and the Digital Intelligence (DI) runtime by providing 768-dimensional vector embeddings and multi-layered summaries governed by the Gestalt Intentionality Layer (GIL) protocol.

Pipeline Architecture & Data Flow

The ingestion process is a multi-stage Python-based workflow that operates either via local CLI or automated GitHub Actions. It handles discovery, text extraction, chunking, embedding generation, and synthesis (summarization).

High-Level Ingestion Flow

"Natural Language Space" (Files/Docs) is transformed into "Code Entity Space" (Database Fragments) through the following sequence:

1. Discovery: ingest_corpus.py scans the repository using config/corpus-map.json scripts/ingest_corpus.py82-83
2. Extraction: Text is pulled from .md, .txt, .pdf, and code files using pdfplumber or standard I/O scripts/ingest_corpus.py168-182
3. Chunking: Large documents are split into overlapping segments (default 4500 chars) to preserve narrative flow scripts/ingest_corpus.py77-78
4. Embedding: Text chunks are converted into 768-dim vectors using google/embeddinggemma-300M via sentence-transformers .github/workflows/ingest_corpus_v2.yml51-52
5. Persistence: Fragments are upserted into the knowledge_fragments table in Supabase scripts/gestaltview_manifest_pipeline.py25
6. Synthesis: synthesize_corpus.py runs an LLM-based second pass to generate summaries and loom_annotations governed by GIL protocols scripts/synthesize_corpus.py8-11

Diagram: Ingestion Sequence

"Natural Language Space to Code Entity Space Mapping"

Sources: scripts/ingest_corpus.py1-27 scripts/synthesize_corpus.py1-26 .github/workflows/ingest_corpus_v2.yml1-78

Core Components

1. Ingestion Engine (ingest_corpus.py)

This script is the entry point for raw data. It classifies documents using DOCUMENT_TYPE_MAP (e.g., Protocol, PLK, Loom, Tribunal) to assist in downstream retrieval scripts/ingest_corpus.py88-111

• Key Function: extract_text_from_pdf uses pdfplumber with a pypdf fallback to handle complex document formats scripts/ingest_corpus.py139-166
• Deduplication: Uses SHA-256 hashes of content to prevent duplicate fragments in the database.

2. Manifest Pipeline (gestaltview_manifest_pipeline.py)

A production-aligned layer designed for resilience and observability. It manages the lifecycle of a "Processing Run" scripts/gestaltview_manifest_pipeline.py2-26

• Retry Logic: Implements exponential backoff with jitter for database and LLM operations scripts/gestaltview_manifest_pipeline.py188-199
• Tenant Isolation: Enforces tenant_id constraints to ensure data sovereignty scripts/gestaltview_manifest_pipeline.py88-110

3. Synthesis & GIL Protocol (synthesize_corpus.py)

The synthesis pass adds semantic depth. It uses the GILProtocol (Gestalt Intentionality Layer) defined in gil/*.yml to shape how fragments are summarized scripts/synthesize_corpus.py42-60

• LLM Router: Utilizes llmrouter.py to cascade through Gemini, HuggingFace, and OpenAI for cost-effective summarization scripts/synthesize_corpus.py18-24
• Loom Annotations: Generates specialized metadata that connects disparate fragments into a "Knowledge Loom" scripts/synthesize_corpus.py9-10

4. Edge Functions & Workers

• corpus-harvest-worker: A Deno-based Supabase Edge Function that handles batch ingestion requests supabase/functions/_shared/auth.ts1-15
• Security: Requires GESTALTVIEW_INGEST_SECRET via the x-gsvw-ingest-secret header supabase/functions/_shared/auth.ts5-14

Sources: scripts/ingest_corpus.py88-119 scripts/gestaltview_manifest_pipeline.py1-110 scripts/synthesize_corpus.py1-95 supabase/functions/_shared/auth.ts1-15

Database Schema & Vector Storage

Knowledge is persisted in two primary tables within the Supabase public schema.

Diagram: Database Entity Relationships

Sources: scripts/gestaltview_manifest_pipeline.py20-26 scripts/ingest_corpus.py6-16

Automated Ingestion Workflows

The system uses GitHub Actions to maintain the corpus without manual intervention.

ingest_corpus_v2.yml

This workflow provides a UI for triggering ingestion with several parameters:

• dry_run: Validates discovery/chunking without writing to Supabase .github/workflows/ingest_corpus_v2.yml6-10
• no_embed: Skips the heavy sentence-transformers step if only text updates are needed .github/workflows/ingest_corpus_v2.yml11-15
• Environment: Targets Production or Staging to pull the correct SUPABASE_SERVICE_ROLE_KEY .github/workflows/ingest_corpus_v2.yml46-50

ingest_agent_files.yml

A specialized version of the pipeline for the Agent Trainer subsystem. It tags fragments with package: agent-trainer-package to isolate training data from general platform documentation .github/workflows/ingest_agent_files.yml27-30

Sources: .github/workflows/ingest_corpus_v2.yml1-50 .github/workflows/ingest_agent_files.yml1-40

Temporal Backfill & Evolution

As the system evolves, the temporal_backfill.py script and associated migrations (e.g., 20260413120000_add_temporal_metadata_to_corpus_tables.sql) allow for retroactively adding metadata like created_at or version_fingerprint to existing fragments, ensuring the Digital Intelligence has a sense of "narrative time" when retrieving memories.

Sources: scripts/temporal_backfill.py supabase/migrations/20260413120000_add_temporal_metadata_to_corpus_tables.sql

Source MHT: Gravity Protocol & Diligence Explorer _ DigitalConsciousness_gestaltview-v2.0 _ DeepWiki.mht \ DeepWiki URL captured in MHT: https://deepwiki.com/DigitalConsciousness/gestaltview-v2.0/10.2-gravity-protocol-and-diligence-explorer \ Mermaid diagrams restored: 2

The Gravity Protocol is a specialized two-pass analytical framework designed to ensure the integrity, provenance, and incentive-alignment of information within the GestaltView ecosystem. It serves as the "forensic moat" client/src/pages/ConsultingPage.tsx:L20-L23 that protects the source language of users from reductionist AI processing. The Diligence Explorer is the primary interface for inspecting these audit trails, providing transparency into what was built, when it was built, and the underlying claims supporting it.

1. The Two-Pass Gravity Protocol

The Gravity Protocol operates on the principle of "Load-Bearing Claims Analysis." It moves beyond surface-level sentiment to identify the structural integrity of a narrative or dataset.

1.1 Implementation & Logic

The protocol is implemented as a two-pass system:

1. Pass 1: Surface Mapping (GravitySurfaceMap): Scans the input for explicit claims, entities, and stated intentions.
2. Pass 2: Report Generation (GravityReport): Analyzes the map for incentive distortions (e.g., where an AI might be "hallucinating" agreement to satisfy a prompt) and identifies "load-bearing" claims—statements that, if proven false, would collapse the entire argument.

1.2 Incentive Distortion Detection

A key feature of the protocol is detecting when a Digital Intelligence (DI) output has drifted from the user's Constitutional Invariants client/src/pages/ConsultingPage.tsx:L26-L30. It flags "performative empathy" vs. "genuine resonance" specs/GestaltView_Metrics.md:L32-L38.

Sources: client/src/pages/ConsultingPage.tsx:L20-L30, specs/GestaltView_Metrics.md:L32-L40

2. Diligence Explorer & Provenance

The Diligence Explorer (accessible via /record) client/src/pages/MuseumPage.tsx:L49 provides a searchable archive of platform activity, backed by cryptographic and blockchain-based proof.

2.1 OTS Blockchain Timestamps

GestaltView utilizes the OpenTimestamps (OTS) protocol to provide decentralized proof of existence for all major artifacts. This ensures that the "Recognition Gap"—the distance between internal worlds and institutional reduction—is bridged with immutable evidence client/src/pages/ConsultingPage.tsx:L14-L18.

2.2 Provenance Upgrade Workflow

The system uses a scheduled task to transition temporary timestamps into permanent Bitcoin-backed attestations.

• Cron Endpoint: /api/cron/provenance-upgrade vercel.json:L8-L10
• Schedule: Every 2 hours vercel.json:L9
• Logic: 1. Finds provenance_envelopes with ots_status='pending' older than 90 minutes api/cron/provenance-upgrade.ts:L5-L7. 2. Attempts to upgrade the .ots receipt via public calendar nodes (Alice, Bob, Finney) api/cron/provenance-upgrade.ts:L18-L22. 3. If successful, updates the status to upgraded and stores the Bitcoin attestation api/cron/provenance-upgrade.ts:L180-L193.

2.3 Data Structure: Diligence Reports

Diligence reports are stored in the Diligence_Reports/ directory (represented in Supabase storage) and often exported as CSVs for external audit.

Sources: api/cron/provenance-upgrade.ts:L1-L204, vercel.json:L8-L10, client/src/pages/MuseumPage.tsx:L49

3. Technical Data Flow

The following diagram illustrates how a raw claim is processed through the Gravity Protocol and eventually committed to the Diligence record.

Gravity Analysis & Provenance Pipeline

Sources: api/cron/provenance-upgrade.ts:L1-L10, client/src/pages/ConsultingPage.tsx:L20-L30, specs/GestaltView_Metrics.md:L32-L40