# VNOS — Architecture Constitution (Executive Baseline)

> **Priority P0 / Non-negotiable.** These principles outrank delivery speed and feature convenience.

## Scope
VNOS is a Dynamic Value Network Operating System for cross-enterprise value networks across industries, **not** a generic no-code application builder, an ERP clone, or a flour-industry-specific app.

## Binding engineering rules
1. **Headless:** Every domain capability runs independently from any UI. Controllers, forms and frontend frameworks cannot own core logic.
2. **API-first:** Every slice defines versioned resource contracts, validation, errors, auth, idempotency and OpenAPI before/alongside implementation; UI consumes the same public application APIs.
3. **Metadata-driven:** Entity/field/relationship/validation/form/workflow definitions are versioned first-class artifacts; runtime applies published versions. Metadata is not permission to execute arbitrary SQL.
4. **Dynamic relational schema:** SQL Server relational-first for core transactions. Schema Engine owns reviewed, validated, transactional/safe migrations for supported structural changes. No raw user-provided DDL, destructive changes without approved migration, or schema mutations per request.
5. **Configuration-first:** Organization roles, workflow rules, price formulae, insurance models, tariffs, share percentages, effective dates and settlement rules must not be embedded as constants.
6. **Platform over pilot:** Ard Varamin, Samira and Ofogh Kourosh are configurable organization records, not core class names, code branches or tenant IDs.
7. **Multi-party, multi-industry:** Ownership, custody, contractual obligation and financial position are independent domain concepts.
8. **Source-agnostic ingest:** Manual/API/batch/ERP/POS sources go through common validation, mapping, provenance, dedupe and discrepancy management; source confidence recorded.
9. **Event-driven reliability:** Domain transactions persist atomically with outbox records; asynchronous consumers are idempotent. Never equate event publication with eventual successful settlement.
10. **Financial truth:** Double-entry journal is balanced, immutable-by-posting and corrected via reversals; accrual vs real bank movement differentiated.
11. **Traceability truth:** Lot genealogy supports many-to-many transformations, measured yield, wastage, mass balance, and evidence grades. POS GTIN alone does not prove batch origin.
12. **Secure extendability:** Contracted slots/adapters/plugins may extend capabilities without bypassing authorization, tenant boundaries, audits or domain invariants.

## Two-plane architecture
- **Control Plane:** Model Studio, Fields, Relation Studio, Rules, Workflow, Integrations, Permissions, Versioning, Publish/rollback.
- **Runtime Plane:** Stable APIs and domain services execute published definitions; background workers and event handlers respect effective versioning.

## Acceptance gate for EVERY vertical slice
- Prove domain command works via API with no UI.
- Prove at least one supported model/field/rule customization without changing core code.
- Demonstrate reuse for a second organization and explain how the same module applies to another industry.
- Document access control, audit, provenance, concurrency, events, error contracts, backward compatibility and tests.
- Failing any applicable gate means **NOT DONE**.

## Limits
Configuration can express **supported** domain variation; novel algorithms/extensions still require versioned code/plugins. Do not claim unlimited runtime schema freedom. Business/legal/financial decisions stay configurable or open until explicitly approved.