From 54181c2def1be72b5b31000f144fd504a8592d50 Mon Sep 17 00:00:00 2001 From: FaikAijaz Date: Sun, 1 Mar 2026 04:11:12 +0530 Subject: [PATCH 1/2] docs: add execution pipeline overview section to README Signed-off-by: FaikAijaz --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 17c96b8..3e8fb01 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,30 @@ At a high-level the template engine converts a TemplateMark DOM to an AgreementM ![Template Interpreter](./assets/template-interpreter.png) +## Execution Pipeline Overview + +Internally, the Template Engine evaluates templates through a structured execution pipeline: + +1. **Type Validation** + The TemplateMark JSON document and the incoming agreement data are validated against their respective Concerto models to ensure structural and type correctness. + +2. **TypeScript Compilation** + Embedded TypeScript expressions (such as conditionals, clauses, and formulae) are compiled into JavaScript using the `TemplateMarkToJavaScriptCompiler`. + +3. **User Code Evaluation** + During agreement generation, compiled JavaScript expressions are evaluated using the `JavaScriptEvaluator`. + The evaluator supports two execution strategies: + - `evalDangerously()` — Executes JavaScript directly within the current process. + - `evalChildProcess()` — Executes JavaScript in an isolated Node.js child process for improved safety and isolation. + +4. **AgreementMark Generation** + The TemplateMark document is traversed, evaluated values are inserted into the document structure, and an AgreementMark JSON document is produced. + +5. **Output Validation** + The generated AgreementMark document is validated before being returned. + +This layered architecture ensures type-safety, deterministic execution of template logic, and isolation during runtime evaluation. + ## Hello World Template Let's create the simplest template imaginable, the infamous "hello world"! From f7d2df0f500710a7835418f088f2fecfb28a514b Mon Sep 17 00:00:00 2001 From: FaikAijaz Date: Mon, 23 Mar 2026 12:37:48 +0530 Subject: [PATCH 2/2] docs: clarify security usage of evalDangerously and evalChildProcess Signed-off-by: FaikAijaz --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3e8fb01..f473135 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,9 @@ Internally, the Template Engine evaluates templates through a structured executi 3. **User Code Evaluation** During agreement generation, compiled JavaScript expressions are evaluated using the `JavaScriptEvaluator`. The evaluator supports two execution strategies: - - `evalDangerously()` — Executes JavaScript directly within the current process. - - `evalChildProcess()` — Executes JavaScript in an isolated Node.js child process for improved safety and isolation. + - `evalDangerously()` — Executes JavaScript directly within the current process. + This should only be used with trusted code or in a sandboxed environment (e.g., browser). + - `evalChildProcess()` — Executes JavaScript in an isolated Node.js child process for improved safety and isolation and is recommended for untrusted template content on the server. 4. **AgreementMark Generation** The TemplateMark document is traversed, evaluated values are inserted into the document structure, and an AgreementMark JSON document is produced.