Carmen LabsCarmen Labs
MView V1

Overview

What a Mutated View is and the model it's built on.

Overview

A Mutated View (MView) is a re-executable, alternate representation of a file or a selection of files within a directory. It does not modify the original source — it produces a separate, persistent artifact that can be re-run whenever the source changes.

original source file
    │
    ▼
Source Adapter
    │
    ▼
normalized input
    │
    ▼
MView parser
    │
    ▼
data model
    │
    ▼
component / Renderer
    │
    ▼
rendered view

The view updates by reading the original source again, running the Source Adapter and parser, and rendering the result. A persisted normalized representation is never the source of truth. For a directory, the runtime reads only the files declared in the manifest. This is the core invariant of the spec: the source is read-only from the MView's perspective.

What an MView is made of

An MView is a small bundle of files:

  • mview.json — the manifest. Identity, versioning, capabilities required, and where to find the parser and component. See the Schema Reference.
  • One or more Source Adapters — interpret the original source file and transform it into normalized input. See Capabilities.
  • A parser module — transforms normalized input into a view-specific data model. See the Parser Contract.
  • A view component — renders that data model with the renderer declared by runtime (for example React, Solid, HTML, PDF, or a custom renderer). See the Component Contract.
  • resources/ (optional) — static assets the component needs (CSS, icons, sample data).

Two placements are valid. Colocated, next to the source file:

sales.csv
sales-dashboard.mview/
├── mview.json
├── parser.ts
├── Dashboard.tsx
└── resources/

Or centralized in a project-level folder, with source.path pointing back at the file:

.mviews/
└── sales-dashboard.mview/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

An MView may also point to a directory, but its manifest must freeze an explicit file selection through source.files. The directory does not grant general access or automatically include all its contents:

reports/
├── january.csv
├── february.csv
└── notes.md
reports-summary.mview/
├── mview.json
├── parser.ts
└── Dashboard.tsx

See Directory Layout for the full discovery convention.

Design invariants

These hold regardless of implementation:

  1. The MView never modifies the source file or files.
  2. The runtime always starts from the original source file; a persisted normalized representation is never the source of truth.
  3. A Source Adapter transforms the physical format into normalized input and does not know the visual data model of a specific MView.
  4. The parser is a pure transform: same input in, same data model out. No filesystem access, no absolute paths.
  5. The component only renders the data model it's given. It does not read files itself.
  6. The runtime — not the adapter, parser, or component — owns file I/O.
  7. Manifests are validated against the published JSON Schema before being loaded or saved.

Next

Descripción general

Qué es una Mutated View y el modelo sobre el que se construye.

Descripción general

Una Mutated View (MView) es una representación alternativa y reejecutable de un archivo o de una selección de archivos dentro de una carpeta. No modifica la fuente original: produce un artefacto separado y persistente que puede volver a ejecutarse cada vez que cambia la fuente.

archivo fuente original
    │
    ▼
Source Adapter
    │
    ▼
entrada normalizada
    │
    ▼
parser de la MView
    │
    ▼
modelo de datos
    │
    ▼
componente / Renderer
    │
    ▼
vista renderizada

La vista se actualiza volviendo a leer el archivo fuente original, ejecutando el Source Adapter y el parser, y renderizando el resultado. No se usa una representación normalizada persistida como fuente de verdad. Para una carpeta, el runtime lee únicamente los archivos declarados en el manifiesto. Esta es la invariante central de la especificación: desde la perspectiva de la MView, la fuente es de solo lectura.

De qué se compone una MView

Una MView es un pequeño paquete de archivos:

  • mview.json — el manifiesto. Identidad, versionado, capacidades requeridas y dónde encontrar el parser y el componente. Ver Referencia del esquema.
  • Uno o más Source Adapters — interpretan el archivo fuente original y lo transforman en una entrada normalizada. Ver Capacidades.
  • Un módulo parser — transforma la entrada normalizada en un modelo de datos específico de la vista. Ver Contrato del parser.
  • Un componente de vista — renderiza ese modelo de datos con el renderer declarado por runtime (por ejemplo React, Solid, HTML, PDF o un renderer propio). Ver Contrato del componente.
  • resources/ (opcional) — assets estáticos que necesita el componente (CSS, iconos, datos de ejemplo).

Estructura recomendada

Hay dos ubicaciones válidas. Colocada junto al archivo fuente:

sales.csv
sales-dashboard.mview/
├── mview.json
├── parser.ts
├── Dashboard.tsx
└── resources/

O centralizada en una carpeta a nivel de proyecto, con source.path apuntando de vuelta al archivo:

.mviews/
└── sales-dashboard.mview/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

Una MView también puede apuntar a una carpeta, pero su manifiesto debe congelar una selección explícita de archivos mediante source.files. La carpeta no concede acceso general ni incluye automáticamente todo su contenido:

reportes/
├── enero.csv
├── febrero.csv
└── notas.md
resumen-reportes.mview/
├── mview.json
├── parser.ts
└── Dashboard.tsx

Ver Estructura de directorios para la convención completa de descubrimiento.

Invariantes de diseño

Se cumplen independientemente de la implementación:

  1. La MView nunca modifica el archivo ni los archivos fuente.
  2. El runtime siempre parte del archivo fuente original; una representación normalizada persistida no es la fuente de verdad.
  3. El Source Adapter transforma el formato físico en una entrada normalizada y no conoce el modelo visual de una MView concreta.
  4. El parser es una transformación pura: misma entrada, mismo modelo de datos. Sin acceso al filesystem, sin rutas absolutas.
  5. El componente solo renderiza el modelo de datos que recibe. No lee archivos por su cuenta.
  6. El runtime, no el adapter, parser ni componente, es dueño de la E/S de archivos.
  7. Los manifiestos se validan contra el JSON Schema publicado antes de cargarse o guardarse.

Siguiente