retold 4.0.1 → 4.0.3

package/docs/architecture/fluid-models.md

@@ -0,0 +1,355 @@
+# Fluid Models
+
+In most application frameworks, a data model is a rigid artifact. You define it once in a migration file or a class, and it becomes the fixed skeleton of your application. Changing it means writing migration scripts, updating API contracts, rebuilding forms, and hoping nothing breaks.
+
+Retold takes a different position: **the model is a living thing**. Data models are easy to describe, easy to mutate, and designed to flow through every layer of the stack — from a terse text definition, through database tables and API endpoints, all the way to browser form fields — adapting their shape at each layer without losing their identity.
+
+## Describing a Model
+
+The fastest way to describe a data model in Retold is Stricture's MicroDDL — a compact text notation where each line defines a column using a single-character sigil.
+
+A classic order management system (think Northwind) might start like this:
+
+```
+!Customer
+@IDCustomer
+%GUIDCustomer
+$CompanyName 128
+$ContactName 128
+$ContactTitle 64
+$Phone 24
+$City 64
+$Country 64
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+
+!Product
+@IDProduct
+%GUIDProduct
+$ProductName 128
+.UnitPrice 10,2
+#UnitsInStock
+~IDSupplier -> IDSupplier
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+
+!Order
+@IDOrder
+%GUIDOrder
+~IDCustomer -> IDCustomer
+&OrderDate
+$ShipCity 64
+$ShipCountry 64
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+
+!OrderDetail
+@IDOrderDetail
+%GUIDOrderDetail
+~IDOrder -> IDOrder
+~IDProduct -> IDProduct
+.UnitPrice 10,2
+#Quantity
+.Discount 5,2
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+```
+
+The sigils are deliberate shorthand:
+
+| Sigil | Type | Example |
+|-------|------|---------|
+| `!` | Table definition | `!Customer` |
+| `@` | Auto-incrementing ID | `@IDCustomer` |
+| `%` | GUID | `%GUIDCustomer` |
+| `$` | String (with size) | `$CompanyName 128` |
+| `#` | Integer | `#UnitsInStock` |
+| `.` | Decimal (precision,scale) | `.UnitPrice 10,2` |
+| `&` | DateTime | `&OrderDate` |
+| `^` | Boolean | `^Deleted` |
+| `~` | Foreign key | `~IDCustomer -> IDCustomer` |
+| `*` | Text (unbounded) | `*Description` |
+
+This is the entire data model for four related entities. No XML, no decorators, no class hierarchies. The definition is compact enough to hold in your head and quick enough to change on a whiteboard.
+
+## One Definition, Many Shapes
+
+From this single MicroDDL source, Stricture generates multiple representations:
+
+```mermaid
+graph LR
+	mddl["MicroDDL<br/><i>Source of truth</i>"]
+	meadow["Meadow Schema<br/><i>JSON column defs,<br/>defaults, validation</i>"]
+	mysql["MySQL Queries<br/><i>CREATE TABLE<br/>statements</i>"]
+	pict["Pict Config<br/><i>Form layouts,<br/>UI metadata</i>"]
+	auth["Authorization<br/><i>Role-based<br/>access rules</i>"]
+
+	mddl --> meadow
+	mddl --> mysql
+	mddl --> pict
+	mddl --> auth
+
+	style mddl fill:#f5f5f5,stroke:#bdbdbd,color:#333
+	style meadow fill:#fff3e0,stroke:#ffa726,color:#333
+	style mysql fill:#fff3e0,stroke:#ffa726,color:#333
+	style pict fill:#f3e5f5,stroke:#ab47bc,color:#333
+	style auth fill:#e3f2fd,stroke:#42a5f5,color:#333
+```
+
+Each output is a different shape of the same logical model:
+
+**Meadow Schema** — JSON column definitions that drive the ORM, query generation, default objects, and JSON Schema validation:
+
+```json
+{
+  "Scope": "Customer",
+  "DefaultIdentifier": "IDCustomer",
+  "Schema": [
+    { "Column": "IDCustomer", "Type": "AutoIdentity" },
+    { "Column": "GUIDCustomer", "Type": "AutoGUID" },
+    { "Column": "CompanyName", "Type": "String", "Size": "128" },
+    { "Column": "ContactName", "Type": "String", "Size": "128" },
+    { "Column": "City", "Type": "String", "Size": "64" },
+    { "Column": "CreateDate", "Type": "CreateDate" },
+    { "Column": "UpdateDate", "Type": "UpdateDate" },
+    { "Column": "Deleted", "Type": "Deleted" }
+  ],
+  "DefaultObject": {
+    "IDCustomer": 0,
+    "GUIDCustomer": "",
+    "CompanyName": "",
+    "ContactName": "",
+    "City": ""
+  }
+}
+```
+
+**MySQL DDL** — CREATE TABLE statements ready to run against a database.
+
+**Pict Configuration** — UI definitions for form views, list views, and record views — which fields to show, how to group them, what input types to use.
+
+## The Model Changes Shape at Every Layer
+
+Consider a modern social platform with Users, Posts, and Comments. Watch how the model's shape changes as it flows through the stack — and how Retold makes that natural rather than painful.
+
+### At the Schema Layer
+
+The MicroDDL is terse and structural:
+
+```
+!User
+@IDUser
+%GUIDUser
+$UserName 64
+$Email 256
+$DisplayName 128
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+
+!Post
+@IDPost
+%GUIDPost
+~IDUser -> IDUser
+$Title 256
+*Body
+&PublishedDate
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+
+!Comment
+@IDComment
+%GUIDComment
+~IDPost -> IDPost
+~IDUser -> IDUser
+*Body
+&CreateDate
+#CreatingIDUser
+&UpdateDate
+#UpdatingIDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser
+```
+
+### At the Database Layer
+
+Meadow consumes the schema and automatically handles audit columns. When you create a Post, you send:
+
+```javascript
+{ Title: 'Hello World', Body: 'First post!', IDUser: 42 }
+```
+
+Meadow merges your data with the schema's default object and fills in the audit columns:
+
+```javascript
+{
+  IDPost: 0,                          // from defaults
+  GUIDPost: '8f14e45f-...',          // auto-generated
+  Title: 'Hello World',              // from your data
+  Body: 'First post!',               // from your data
+  IDUser: 42,                        // from your data
+  PublishedDate: null,                // from defaults
+  CreateDate: '2025-02-17 14:30:00', // auto-stamped
+  CreatingIDUser: 42,                // auto-stamped from session
+  UpdateDate: '2025-02-17 14:30:00', // auto-stamped
+  UpdatingIDUser: 42,                // auto-stamped from session
+  Deleted: 0                         // from defaults
+}
+```
+
+The schema knows which columns are audit columns by their type (`CreateDate`, `UpdateDate`, `Deleted`). Meadow inspects the schema on every operation — not just at startup — so changing the schema changes behavior immediately.
+
+### At the Query Layer
+
+FoxHound reads the schema to generate intelligent queries. If the schema includes a `Deleted` column with type `Deleted`, every read query automatically adds `WHERE Deleted = 0`. You never write that filter. The schema declares the intent; the query layer implements it.
+
+```javascript
+// You write:
+_PostMeadow.doReads(_PostMeadow.query.addFilter('IDUser', 42), fCallback);
+
+// FoxHound generates (simplified):
+// SELECT * FROM Post WHERE IDUser = 42 AND Deleted = 0
+```
+
+### At the API Layer
+
+Meadow-Endpoints reads the same schema and generates a full REST API. The schema's authorization rules control who can do what:
+
+```
+GET  /Posts              → list (filtered by Deleted automatically)
+GET  /Post/42            → read single
+POST /Post               → create (audit columns auto-stamped)
+PUT  /Post               → update (UpdateDate auto-stamped)
+DEL  /Post/42            → soft delete (sets Deleted = 1)
+GET  /Post/Schema        → returns the live schema JSON
+```
+
+The `GET /Post/Schema` endpoint is important — it exposes the current schema to any client. This means the model is not hidden inside server code. It is a queryable, inspectable resource.
+
+### At the UI Layer
+
+Pict reads the schema through Manyfest descriptors and generates form fields. Each column gains UI metadata:
+
+```javascript
+{
+  Hash: 'Title',
+  Name: 'Post Title',
+  DataType: 'String',
+  PictForm: {
+    InputType: 'TextInput',
+    Section: 'PostDetails',
+    Row: 0
+  }
+}
+```
+
+The same address notation — `Record.Title`, `AppData.Posts[0].Body` — works in templates, in code, and in form bindings. Manyfest provides safe navigation that never throws on missing paths, so the UI does not break when the model evolves.
+
+## Runtime Mutation
+
+The model is not frozen after compilation. Meadow schemas are live objects with independent, replaceable parts:
+
+```javascript
+// Load initial schema
+_PostMeadow.loadFromPackage('./Post-Schema.json');
+
+// Later, update just the column definitions
+_PostMeadow.setSchema(updatedColumnArray);
+
+// Or just the validation rules
+_PostMeadow.setJsonSchema(updatedValidationSchema);
+
+// Or just the default values
+_PostMeadow.setDefault({ ...existingDefaults, NewField: 'default' });
+
+// Or just the authorization policies
+_PostMeadow.setAuthorizer(updatedAuthRules);
+```
+
+Each part — column definitions, JSON Schema validation, default objects, authorization — can be modified independently. When you call `setSchema()`, the change propagates immediately to the database provider. Subsequent queries, creates, and updates use the new definition. There is no restart, no cache flush, no migration ceremony.
+
+This matters for real applications. A bookstore that adds a `Price` column to its `Book` entity:
+
+```javascript
+// Existing schema
+let schema = _BookMeadow.schema;
+
+// Add the new column
+schema.push({ Column: 'Price', Type: 'Decimal', Size: '10,2' });
+
+// Update live
+_BookMeadow.setSchema(schema);
+_BookMeadow.setDefault({ ...existingDefaults, Price: 0.0 });
+
+// All subsequent operations include Price
+```
+
+The database table still needs an `ALTER TABLE` — Retold does not run migrations for you. But the application layer adapts instantly. You can evolve the schema in code, test the new shape, and apply the database change when ready.
+
+## Address-Based Access Across Layers
+
+Manyfest provides the glue that makes model fluidity practical. Every piece of data in a Retold application is reachable through an address — a dot-notation string like `Record.Contact.Email` or `AppData.Posts[0].Title`.
+
+```javascript
+// Safe read — returns undefined if any part of the path is missing
+let title = _Manyfest.getValueAtAddress(pRecord, 'Posts[0].Title');
+
+// Safe write — creates intermediate objects as needed
+_Manyfest.setValueAtAddress(pRecord, 'Posts[0].Title', 'Updated Title');
+```
+
+The same address notation works in Pict templates:
+
+```
+{~Data:Record.Title~}
+{~Data:AppData.Posts[0].Title~}
+{~Data:Bundle.Authors.ByID.42.Name~}
+```
+
+And in form bindings, where the template address maps directly to a Manyfest descriptor, which maps to a Meadow column, which maps to a database field. One notation from top to bottom.
+
+When the model changes shape — a field is renamed, a nested object is restructured, a new relationship is added — the address is the single point of update. Change the address in the Manyfest descriptor and every layer that references it adapts.
+
+## Why This Matters
+
+In a traditional framework, changing a data model means touching every layer: migration files, ORM classes, API serializers, validation schemas, form definitions, and template bindings. Each layer has its own notation for describing the same thing, and keeping them synchronized is the source of a large class of bugs.
+
+Retold's approach is different:
+
+- **One source** (MicroDDL) generates all layer-specific representations
+- **One notation** (Manyfest addresses) accesses data everywhere
+- **One schema object** (Meadow) drives queries, validation, defaults, and authorization
+- **Live mutation** means the model evolves without restarts or redeployment ceremonies
+- **Schema introspection** at operation time means changes take effect immediately
+
+The model is not a static artifact that you deploy and forget. It is a fluid description that adapts to each layer's needs and evolves with your application.

package/docs/architecture/module-architecture.md

@@ -0,0 +1,234 @@
+# Ecosystem Architecture - Module Philosophy
+
+Retold modules each embody a specific design philosophy. Together they form a coherent system for building applications — from the stateless service core, through data access and API generation, up to state-driven UI rendering.  At the same time, each module is designed to be used (*and useful*) independently. You can adopt Fable's configuration and logging without using Pict. You can use Meadow for data access without Orator. These modules are decoupled by design, but also fit together in a complementary way.
+
+```mermaid
+graph TB
+	subgraph Clients["Client Applications"]
+		direction LR
+		browser["Browser App<br/><i>Pict + Pict-Application<br/>+ Pict-Views</i>"]
+		console["Console App<br/><i>Pict + Terminal UI</i>"]
+		cli["CLI Tool<br/><i>CommandLineUtility</i>"]
+	end
+
+	internet(("The Internet<br/>☁"))
+
+	subgraph Server["Server / Mid-Tier"]
+		direction TB
+		orator["Orator<br/><i>HTTP Server Abstraction</i>"]
+		endpoints["Meadow-Endpoints<br/><i>Auto-generated REST API</i>"]
+		meadow["Meadow<br/><i>Data Access Abstraction</i>"]
+
+		subgraph DataTools["Schema & Query Tools"]
+			direction LR
+			foxhound["FoxHound<br/><i>Query Generation</i>"]
+			stricture["Stricture<br/><i>MicroDDL → Schema</i>"]
+		end
+
+		orator --> endpoints
+		endpoints --> meadow
+		meadow --> DataTools
+	end
+
+	subgraph Foundation["Foundation (Stateless)"]
+		direction LR
+		fable["Fable<br/><i>DI, Config, Logging</i>"]
+		manyfest["Manyfest<br/><i>Address-Based<br/>Object Access</i>"]
+	end
+
+	Clients -- "HTTP requests" --> internet
+	internet -- "HTTP requests" --> orator
+
+	browser -. "Fable services" .-> Foundation
+	Server --> Foundation
+
+	style Clients fill:#e8f5e9,stroke:#43a047,color:#333
+	style browser fill:#fff,stroke:#66bb6a,color:#333
+	style console fill:#fff,stroke:#66bb6a,color:#333
+	style cli fill:#fff,stroke:#66bb6a,color:#333
+	style internet fill:#e1f5fe,stroke:#03a9f4,color:#333,stroke-width:2px
+	style Server fill:#e3f2fd,stroke:#42a5f5,color:#333
+	style orator fill:#fff,stroke:#64b5f6,color:#333
+	style endpoints fill:#fff,stroke:#64b5f6,color:#333
+	style meadow fill:#fff3e0,stroke:#ffa726,color:#333
+	style DataTools fill:#fff8e1,stroke:#ffcc80,color:#333
+	style foxhound fill:#fff,stroke:#ffcc80,color:#333
+	style stricture fill:#fff,stroke:#ffcc80,color:#333
+	style Foundation fill:#fce4ec,stroke:#ef5350,color:#333
+	style fable fill:#fff,stroke:#ef9a9a,color:#333
+	style manyfest fill:#fff,stroke:#ef9a9a,color:#333
+```
+
+Clients — browsers, terminals, CLI tools — communicate with the server over HTTP. Orator receives those requests, Meadow-Endpoints maps them to data operations, and Meadow executes them against the database. Fable provides the stateless service container that every module on both sides of the network depends on. Manyfest provides the consistent data-addressing language used everywhere.
+
+---
+
+## Fable Is Stateless
+
+Fable draws a hard line between **configuration** and **state**.
+
+In Retold's vocabulary, *state* is **application data** — the records in a database, the items in a shopping cart, the text a user has typed into a form. State changes as users interact with the system. It is the core subject matter of the application.
+
+Configuration is everything else: the address of the database server, the port the API listens on, the log level, the product name. Configuration describes how the application runs in its environment, not what the application is doing. Fable manages configuration. It does not manage state.
+
+This distinction matters because the "Out of the Tar Pit" problem — the paper Fable's design references — identifies uncontrolled state as the primary source of software complexity. By keeping the service container stateless, Fable ensures that the foundation layer has no opinion about your data. Services register with Fable, receive configuration and logging, and operate on whatever data flows through them without Fable holding onto it.
+
+Every Retold module extends `fable-serviceproviderbase` and registers with a Fable instance. That instance provides dependency injection, logging, UUID generation, and shared settings. But the Fable instance itself stores no application data. It is the wiring, not the warehouse.
+
+## Pict Is for State and Transformation
+
+If Fable is deliberately stateless, Pict is deliberately stateful. Pict's job is to hold application state and transform it consistently into output using a templating language.
+
+Pict provides three dedicated state containers:
+
+| Container | Purpose | Example Contents |
+|-----------|---------|------------------|
+| **AppData** | Primary application state | User records, form values, loaded entities |
+| **Bundle** | Supporting reference data | Lookup tables, dropdown options, translations |
+| **TempData** | Ephemeral intermediate data | Chart caches, calculated summaries, UI flags |
+
+All state lives in known locations. Templates reference state through address expressions like `AppData.Tasks[0].Name`. Code accesses the same state through the same addresses. There is one source of truth and one notation for reaching it.
+
+The key insight is that **state and lifecycle are coupled**. Pict's lifecycle phases — Solve, Render, Marshal — all operate on these state containers:
+
+1. **Solve** reads state and writes derived values back into state
+2. **Render** reads state and produces output through templates
+3. **Marshal** collects input and writes it back into state
+
+This cycle is predictable and debuggable. At any point in the lifecycle you can inspect the state containers and know exactly what data the application is working with.
+
+Pict intentionally separates logic from templates. Templates describe *what* to render; code (in views and providers) describes *when* and *how* data moves. You can override templates without altering behavior, and you can alter behavior without touching templates.
+
+## Pict-Application Manages the Lifecycle
+
+Pict-Application is the orchestration layer. It coordinates the startup, data loading, solving, rendering, and marshaling of an entire application composed of multiple views and providers.
+
+The lifecycle follows a defined sequence:
+
+```mermaid
+graph LR
+	init["Initialize<br/><i>Register views,<br/>providers, templates</i>"]
+	data["Load Data<br/><i>Fetch from APIs,<br/>populate AppData</i>"]
+	solve["Solve<br/><i>Calculate derived<br/>values</i>"]
+	render["Render<br/><i>Transform state<br/>into output</i>"]
+	marshal["Marshal<br/><i>Collect input<br/>back into state</i>"]
+
+	init --> data --> solve --> render --> marshal
+	marshal -. "user interaction" .-> solve
+
+	style init fill:#fce4ec,stroke:#ef5350,color:#333
+	style data fill:#fff3e0,stroke:#ffa726,color:#333
+	style solve fill:#e8f5e9,stroke:#43a047,color:#333
+	style render fill:#e3f2fd,stroke:#42a5f5,color:#333
+	style marshal fill:#f3e5f5,stroke:#ab47bc,color:#333
+```
+
+Each view and provider within the application participates in these phases. Pict-Application ensures they execute in the correct order (controlled by configurable ordinals) and provides auto-behaviors to reduce boilerplate — for example, automatically solving and rendering after initialization completes.
+
+The application also manages authentication flows, data loading sequences, and the coordination between views that need to share state. It is the conductor; views and providers are the musicians.
+
+## Pict-View Is Not Just a Screen
+
+A Pict view is any representation of information. It is not a page. It is not a screen. It is not a route.
+
+A single screen might contain dozens of views: a header view, a navigation view, a list view, a detail panel view, a status bar view. Or a single view might render to a log file, a terminal widget, or a test harness instead of a browser DOM. The view is the unit of *rendering*, not the unit of *navigation*.
+
+Each view contains **renderables** — individual render instructions that specify:
+
+- Which **template** to use
+- Which **data address** to read from state
+- Which **destination** to render into
+- Which **method** to use (replace, append, prepend)
+
+This makes views composable. Small views handle small concerns. Larger patterns emerge from combining them. A form section view renders input fields. A recordset view renders a list of records. A content view renders static markup. You assemble an application from these building blocks.
+
+Because views render through a content assignment abstraction, they are not bound to the browser DOM. The same view code can render to a blessed terminal widget, a log stream, or a mock environment for testing — by swapping the content assignment functions. The view does not know or care where its output ends up.
+
+## Orator Abstracts Web Servers
+
+Orator provides a thin abstraction over HTTP servers. Your application code interacts with Orator's interface — defining routes, middleware, and lifecycle hooks — without coupling to a specific server implementation.
+
+The default implementation uses Restify (`orator-serviceserver-restify`), but the abstraction means you could swap in a different HTTP library or use IPC mode for testing without changing application routes or middleware. Orator handles the HTTP lifecycle: receiving requests, running middleware, dispatching to handlers, and sending responses.
+
+Orator also provides static file serving (`orator-static-server`) and reverse proxy capabilities (`orator-http-proxy`), making it a complete server-side HTTP toolkit without being a heavyweight framework.
+
+The philosophy is deliberate thinness. Orator does not dictate application structure. It provides the plumbing for getting HTTP requests to your code and responses back to the client.
+
+## Meadow Abstracts Data Access
+
+Meadow is a provider-agnostic data broker. You define entities once — their fields, types, and relationships — and Meadow handles CRUD operations against whatever database is connected.
+
+The abstraction has real teeth: the same Meadow entity definition works with MySQL, MSSQL, SQLite, and ALASQL (for in-browser use). Switch databases by swapping a connection module. Your application code, entity definitions, and endpoint configurations do not change.
+
+Meadow automatically manages audit columns (who created a record, who last updated it, and when), soft deletes (marking records as deleted without removing them), GUID-based uniqueness, and data marshalling between JavaScript objects and database rows.
+
+The data access pattern is deliberately simple: Create, Read, Reads (list), Update, Delete, Count, and Undelete. These seven operations cover the vast majority of data access needs. When they do not, behavior hooks let you inject custom logic at any point in the operation lifecycle.
+
+## Meadow-Endpoints Connects Data Access to a Consistent API
+
+Meadow-Endpoints takes a Meadow entity and automatically generates a full REST API for it. Define an entity called `Book` and you immediately get `GET /Books`, `GET /Book/:id`, `POST /Book`, `PUT /Book`, `DEL /Book/:id`, and more — with filtering, pagination, sorting, and schema introspection built in.
+
+This is not code generation that produces files you maintain. The endpoints are generated at runtime from the entity definition. Change the schema, restart the server, and the API updates. Add a new entity, wire it to Meadow-Endpoints, and the routes appear.
+
+Behavior hooks provide the extension points. Need authentication? Add a `before` hook. Need to transform data before it reaches the client? Add an `after` hook. Need custom validation? Hook into the create and update paths. The auto-generated API is the foundation; hooks let you customize without replacing it.
+
+## FoxHound Generates Queries
+
+FoxHound is the query generation engine inside Meadow. It provides a chainable API for building queries — adding filters, setting sort order, configuring pagination — and then generates the correct SQL dialect for whichever database you are using.
+
+```javascript
+_Query.addFilter('Status', 'Complete')
+      .setSort('CreatedDate')
+      .setBegin(0).setCap(50)
+      .buildReadQuery();
+```
+
+This same code produces valid MySQL, MSSQL, SQLite, or ALASQL depending on the dialect. Application code never writes raw SQL. FoxHound's job is to be the single translation layer between a database-agnostic query description and dialect-specific SQL.
+
+FoxHound also powers the **FilteredTo** URL syntax used by Meadow-Endpoints, which encodes filters, sorts, and pagination into URL paths for GET requests. This means clients can express complex queries through standard HTTP URLs without POST bodies.
+
+## Stricture Transforms MicroDDL into Schemas
+
+Stricture provides a compact notation — MicroDDL — for defining data models. A MicroDDL file is a human-readable text format where each line defines a column using single-character sigils:
+
+```
+!ID
+@GUIDTask
+#Name
+#Description
+#Status
+&Hours
+%Due
+```
+
+From this terse input, Stricture generates:
+
+- **JSON schemas** for Meadow entity definitions
+- **CREATE TABLE statements** for MySQL, MSSQL, or SQLite
+- **Documentation** describing the data model
+- **Seed data templates** for testing
+
+The philosophy is *define once, generate everywhere*. The MicroDDL is the single source of truth for a data model. Every downstream artifact — database tables, API schemas, documentation — derives from it. Change the MicroDDL, regenerate, and all representations stay in sync.
+
+## Manyfest Provides Address-Based Object Access
+
+Manyfest solves a recurring problem: the same data structure is described and accessed differently at every layer of an application. The database has column names. The API has JSON keys. The frontend has display labels. Business logic has domain terms.
+
+Manyfest unifies this through **address-based access**. An address is a string like `Record.Contact.Email` that describes a location in a nested JavaScript object. Manyfest provides safe accessors that navigate the address without throwing exceptions on missing intermediate objects:
+
+```javascript
+// Safe read — returns undefined if any part of the path is missing
+let email = _Manyfest.getValueAtAddress(pRecord, 'Contact.Email');
+
+// Safe write — creates intermediate objects as needed
+_Manyfest.setValueAtAddress(pRecord, 'Contact.Email', 'new@example.com');
+```
+
+Beyond safe access, Manyfest provides **descriptors** — metadata that maps addresses to human-readable names, short names, descriptions, data types, and hashes. This means a single Manyfest definition can drive:
+
+- API field documentation
+- Form field labels and validation
+- Report column headers
+- Data transformation between layers
+
+The address notation is the same notation Pict uses for template expressions and state access. This consistency means a Manyfest schema defined for the data layer can flow all the way through to form labels in the browser without translation.