# 📘 Final Specification: App-Graph DSL (v1.0)

## 1. Overview
The **App-Graph DSL** is a high-velocity, text-to-graph language designed for mobile-first orchestration of business and software processes. It transforms a linear string of text into a **Directed Acyclic Graph (DAG)**, where nouns represent state and verbs represent actions.

### Core Philosophy
*   **Zero-Friction:** Minimal keystrokes; no braces, no quotes, no complex symbols.
*   **Implicit Creation:** If a noun is referenced and does not exist, the system instantiates it using a default template.
*   **Synchronous Flow:** The `>` operator ensures that a node must return a `SUCCESS` state before the next node begins.

---

## 2. The Grammar (Syntax Map)

| Symbol | Name | Function | Example |
| :--- | :--- | :--- | :--- |
| **`.`** | **Dot** | Defines an Entity or Property | `User.Profile` |
| **`>`** | **Arrow** | Synchronous Transition (Wait for prev) | `Node A > Node B` |
| **`/`** | **Slash** | Triggers a Verb, Function, or Filter | `/Verify` |
| **` `** | **Space** | Start of Arguments | `/Wait 1h` |
| **`:`** | **Colon** | Key-Value Assignment | `msg:Hello` |
| **`,`** | **Comma** | Argument Separator | `key1:val1, key2:val2` |
| **`.Prog`**| **Modifier** | Activates Live Progress Bar | `/Upload.Prog` |

### Argument Logic (JSON-Lite)
To avoid mobile keyboard switching, arguments are passed as plain text.
*   **Single Value:** `/Wait 1h`> `{"duration": "1h"}`
*   **Multi-Value:** `/Setup reg:EU, curr:USD` > `{"region": "EU", "currency": "USD"}`

---

## 3. The Engine Logic (Execution Blueprint)

### A. The Node Types
1.  **Noun (`Noun.Prop`):**
    *   Checks if the object exists in the state database.
    *   If **Yes**: Sets it as the current context.
    *   If **No**: Creates the object based on the `Noun` type template.
2.  **Verb (`/Verb`):**
    *   Executes a function using the current noun as the input.
    *   Returns a result that is passed to the next node.
3.  **Filter (`/Filter`):**
    *   A Boolean gate. If the condition is `True`, the flow continues. If `False`, the chain terminates (or jumps to a `/Catch` if present).
4.  **Interaction (`/Ask`):**
    *   Pauses the graph. Triggers a UI modal. Awaits a user response before resuming.
5.  **Temporal (`/Wait`):**
    *   Suspends the graph. Schedules a wake-up trigger for the specified time.

### B. The Flow of a Request
`Input String` > `Lexer (Split by >)` > `Parser (Identify Noun vs Verb)` > `State Resolver (Resolve Nouns)` > `Executor (Run Verbs in order)` > `UI Update (Progress/Notify)`.

---

## 4. Comprehensive Implementation Examples

### 🏢 Category 1: General Company Operations
*Managing the "Human" and "Legal" side of a business.*

**1. New Employee Onboarding**
`Employee.New > /VerifyID > /SetAccess dept:Engineering, level:L2 > /Create.Account type:Email > /Notify msg:Welcome to the team!`
*   *Logic: Create employee > Verify ID > Grant permissions > Create email > Send welcome.*

**2. Automated Sales Outreach**
`Lead.List > /Filter score:high > /SendEmail template:intro > /Wait 3d > /Filter replied:false > /SendEmail template:followup > /Notify sales:Lead Needs Attention`
*   *Logic: Target high-value leads > Email them > Wait 3 days > If no reply, send followup > Alert sales rep.*

**3. Legal Contract Execution**
`Contract.NDA > /SendSignature signee:client > /Ask msg:Has client signed? type:bool > /Filter signed:true > /Archive folder:Legal_2024 > /Notify msg:NDA Complete`
*   *Logic: Initiate NDA > Send for sig > Wait for human confirmation > If true, archive and notify.*

---

### 💻 Category 2: Software & Engineering
*Managing the "Technical" side of a product.*

**4. CI/CD Deployment Pipeline**
`Code.Main > /Lint > /Test.Prog > /Filter passed:true > Server.Staging > /Deploy > /Notify msg:Staging Updated`
*   *Logic: Pull code > Lint > Run tests (with progress bar) > If passed, deploy to staging > Notify team.*

**5. Incident Response (SRE)**
`Alert.Sentry > /Filter severity:crit > /Notify admin:OnCall > /Ask msg:Reboot Server? type:bool > /Filter approved:true > /Reboot.Prog > /Notify msg:System Recovered`
*   *Logic: Critical alert > Notify on-call > Ask for reboot permission > If yes, reboot (with progress) > Final notification.*

**6. Database Migration**
`DB.Backup > /VerifyIntegrity > /Migration.Prog target:Production > /Filter status:success > /Notify msg:Migration Done > /Cleanup logs:old`
*   *Logic: Backup DB > Check backup > Migrate (with progress) > If success, notify and clean up.*

---

### 💰 Category 3: Financials & Payments
*Managing the "Money" side of the company.*

**7. Overdue Invoice Recovery**
`Invoice.Pending > /Wait 7d > /Filter paid:false > /Reminder msg:Payment Overdue > /Wait 3d > /Filter paid:false > /Notify acc:Finance, priority:high`
*   *Logic: Check pending invoices > Wait a week > If unpaid, send reminder > Wait 3 more days > If still unpaid, escalate to Finance.*

**8. SaaS Subscription Upgrade**
`User.Account > /UpgradePlan plan:Enterprise > /ChargeCard amount:500, curr:USD > /Filter success:true > /SetAccess features:all > /Notify msg:Welcome to Enterprise!`
*   *Logic: Target user > Trigger upgrade > Charge card > If successful, unlock features > Notify.*

---

## 5. Quick-Reference Summary Table

| Scenario | Syntax Example | Key Feature Used |
| :--- | :--- | :--- |
| **Onboarding** | `Emp.New > /VerifyID > /Notify` | Implicit Creation |
| **Deployment** | `Code.Main > /Test.Prog > /Deploy` | `.Prog` Modifier |
| **Sales** | `Lead.List > /Filter score:high > /Send` | Collection Loop + Filter |
| **Support** | `Ticket.New > /Ask msg:Help? > /Solve` | `/Ask` Interaction |
| **Compliance** | `User.New > /Wait 24h > /VerifyEmail` | `/Wait` Temporal |
| **Payment** | `Bill > /Charge > /Filter success:true` | Blocking Synchronicity (`>`) |