graphenix-format 1.2.0 → 1.3.0

package/README.md

@@ -267,6 +267,52 @@ The minimal example graph lives in `src/examples/minimal-graph.ts` and mirrors t
 
 ---
 
+### Worox-graph alignment (`metadata.graphEntry` / `metadata.graphResponse`)
+
+Worox-graph attaches **entry** and **response** contracts to graph JSON; graphenix-format exposes the same shapes as **optional fields on the graph document**:
+
+| Field | Type | Role |
+|-------|------|------|
+| `metadata.graphEntry` | `GraphEntryContract` | Entry / execution expectations |
+| `metadata.graphResponse` | `GraphResponseContract` | Final output shape |
+
+**`GraphEntryContract`** may include:
+
+- `summary` — short description of what the graph expects at entry.
+- `requiredExecutionPaths` / `notableExecutionPaths` — path descriptors (engine-specific item shapes).
+- `executionSchema` — JSON Schema for the merged **execution** object after entry (optional tooling validation only).
+
+**`GraphResponseContract`** may include:
+
+- `summary` — description of the response.
+- `finalOutputSchema` — JSON Schema for the **final output** value (optional tooling validation only).
+
+**I/O visibility layers (single narrative for authors):**
+
+- **Layer 01** — **Entry**: what must be satisfied when the graph is invoked; described by `graphEntry` (`summary`, paths, `executionSchema`).
+- **Layer 08** — **Response**: what leaves the graph as the final result; described by `graphResponse` (`summary`, `finalOutputSchema`).
+
+Optional **AJV** checks (not required for graphenix planning):
+
+```ts
+import {
+  validateGraph,
+  validateExecutionAgainstContract,
+  validateFinalOutputAgainstContract,
+  type GraphDocument
+} from "@graphenix/format";
+
+const doc: GraphDocument = /* ... with metadata.graphEntry / metadata.graphResponse ... */;
+
+validateGraph(doc);
+validateExecutionAgainstContract(doc, mergedExecution);
+validateFinalOutputAgainstContract(doc, finalOutput);
+```
+
+For how worox-graph’s task/DAG JSON differs from port-based `Graph`, see [`docs/interop-worox-graph.md`](docs/interop-worox-graph.md).
+
+---
+
 ### Notes
 
 - The package is **execution-agnostic**: it only knows about the static Graphenix format.

package/dist/examples/validate-minimal.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const validate_1 = require("../validate");
+const validateWorox_1 = require("../validateWorox");
 const minimal_graph_1 = require("./minimal-graph");
 const result = (0, validate_1.validateGraph)(minimal_graph_1.minimalGraph);
 if (!result.valid) {
@@ -10,4 +11,40 @@ if (!result.valid) {
 else {
     console.log("Minimal graph is valid according to Graphenix format 1.0.0");
 }
+const withWoroxMetadata = {
+    ...minimal_graph_1.minimalGraph,
+    metadata: {
+        graphEntry: {
+            summary: "Smoke-test entry contract",
+            requiredExecutionPaths: [["node:validate-input"]],
+            executionSchema: {
+                type: "object",
+                properties: { ok: { type: "boolean" } },
+                required: ["ok"]
+            }
+        },
+        graphResponse: {
+            summary: "Smoke-test response contract",
+            finalOutputSchema: { type: "string", minLength: 1 }
+        }
+    }
+};
+const woroxDoc = (0, validate_1.validateGraph)(withWoroxMetadata);
+if (!woroxDoc.valid) {
+    console.error("Worox metadata document is INVALID", woroxDoc.errors);
+    process.exitCode = 1;
+}
+const execOk = (0, validateWorox_1.validateExecutionAgainstContract)(withWoroxMetadata, { ok: true });
+const execBad = (0, validateWorox_1.validateExecutionAgainstContract)(withWoroxMetadata, {});
+const outOk = (0, validateWorox_1.validateFinalOutputAgainstContract)(withWoroxMetadata, "done");
+const outBad = (0, validateWorox_1.validateFinalOutputAgainstContract)(withWoroxMetadata, "");
+if (!execOk.valid || execBad.valid || !outOk.valid || outBad.valid) {
+    console.error("Worox runtime validation smoke test failed", {
+        execOk,
+        execBad,
+        outOk,
+        outBad
+    });
+    process.exitCode = 1;
+}
 //# sourceMappingURL=validate-minimal.js.map

package/dist/examples/validate-minimal.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-minimal.js","sourceRoot":"","sources":["../../src/examples/validate-minimal.ts"],"names":[],"mappings":";;AAAA,0CAA4C;AAC5C,mDAA+C;AAE/C,MAAM,MAAM,GAAG,IAAA,wBAAa,EAAC,4BAAY,CAAC,CAAC;AAE3C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,4DAA4D,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"validate-minimal.js","sourceRoot":"","sources":["../../src/examples/validate-minimal.ts"],"names":[],"mappings":";;AAAA,0CAA4C;AAC5C,oDAG0B;AAE1B,mDAA+C;AAE/C,MAAM,MAAM,GAAG,IAAA,wBAAa,EAAC,4BAAY,CAAC,CAAC;AAE3C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,4DAA4D,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,iBAAiB,GAAkB;IACvC,GAAG,4BAAY;IACf,QAAQ,EAAE;QACR,UAAU,EAAE;YACV,OAAO,EAAE,2BAA2B;YACpC,sBAAsB,EAAE,CAAC,CAAC,qBAAqB,CAAC,CAAC;YACjD,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;gBACvC,QAAQ,EAAE,CAAC,IAAI,CAAC;aACjB;SACF;QACD,aAAa,EAAE;YACb,OAAO,EAAE,8BAA8B;YACvC,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;SACpD;KACF;CACF,CAAC;AAEF,MAAM,QAAQ,GAAG,IAAA,wBAAa,EAAC,iBAAiB,CAAC,CAAC;AAClD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACpB,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,MAAM,GAAG,IAAA,gDAAgC,EAAC,iBAAiB,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACjF,MAAM,OAAO,GAAG,IAAA,gDAAgC,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AACxE,MAAM,KAAK,GAAG,IAAA,kDAAkC,EAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;AAC5E,MAAM,MAAM,GAAG,IAAA,kDAAkC,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AAEzE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;IACnE,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE;QAC1D,MAAM;QACN,OAAO;QACP,KAAK;QACL,MAAM;KACP,CAAC,CAAC;IACH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./types";
 export * from "./validate";
+export * from "./validateWorox";
 export * from "./crud";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}

package/dist/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./validate"), exports);
+__exportStar(require("./validateWorox"), exports);
 __exportStar(require("./crud"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,kDAAgC;AAChC,yCAAuB"}

package/dist/types.d.ts

@@ -82,15 +82,68 @@ export interface SubgraphDefinition {
     metadata?: Record<string, unknown>;
     extensions?: Record<string, unknown>;
 }
+/**
+ * JSON Schema object (typically draft-07) used by tooling to validate runtime payloads.
+ * Kept as a generic object so authors can use `$ref`, `definitions`, etc.
+ */
+export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * Worox-graph entry contract: describes expected execution inputs and structure.
+ * Aligns with `@woroces/worox-graph` `GraphEntryContract` (I/O visibility **layer 01**).
+ */
+export interface GraphEntryContract {
+    /** Short human-readable description of what the graph expects at entry. */
+    summary?: string;
+    /**
+     * Path descriptors for execution branches that must run (shape is engine-specific;
+     * often node-id lists or segmented paths).
+     */
+    requiredExecutionPaths?: unknown[];
+    /**
+     * Optional JSON Schema for the merged **execution** object after graph entry
+     * (validated separately with `validateExecutionAgainstContract` when tooling enables it).
+     */
+    executionSchema?: JsonSchemaObject;
+    /** Notable or optional execution paths for diagnostics or docs. */
+    notableExecutionPaths?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Worox-graph response contract: describes the final output shape.
+ * Aligns with `@woroces/worox-graph` `GraphResponseContract` (I/O visibility **layer 08**).
+ */
+export interface GraphResponseContract {
+    summary?: string;
+    /**
+     * JSON Schema for the graph **final output** value
+     * (validated separately with `validateFinalOutputAgainstContract` when tooling enables it).
+     */
+    finalOutputSchema?: JsonSchemaObject;
+    [key: string]: unknown;
+}
+/**
+ * Optional document-level metadata. Known keys `graphEntry` / `graphResponse` mirror
+ * worox-graph graph JSON and are copied to `variables.__graphModel` by consumers.
+ */
+export type GraphDocumentMetadata = {
+    graphEntry?: GraphEntryContract;
+    graphResponse?: GraphResponseContract;
+} & Record<string, unknown>;
 export interface GraphDocument {
     formatVersion: string;
     id: string;
     name?: string;
     description?: string;
     tags?: string[];
+    /** Structural graph (ports, `GraphInput` / `GraphOutput`). */
     graph: Graph;
     types?: TypeDefinition[];
     subgraphs?: SubgraphDefinition[];
+    /**
+     * Optional worox-graph-aligned contracts for planning and I/O documentation.
+     * Prefer this surface over duplicating the same data only under `extensions`.
+     */
+    metadata?: GraphDocumentMetadata;
     extensions?: Record<string, unknown>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validateWorox.d.ts

@@ -0,0 +1,22 @@
+import Ajv from "ajv";
+import type { GraphDocument } from "./types";
+import type { ValidationResult } from "./validate";
+export interface WoroxRuntimeValidationOptions {
+    /**
+     * AJV instance used to compile `executionSchema` / `finalOutputSchema`.
+     * When omitted, a shared default instance (`strict: false`, `allErrors: true`) is used.
+     */
+    ajv?: Ajv;
+}
+/**
+ * Validates `execution` against `document.metadata.graphEntry.executionSchema` when present.
+ * If there is no schema, or `graphEntry` is missing, returns `{ valid: true, errors: [] }`.
+ * This is optional tooling; graphenix planning does not require it.
+ */
+export declare function validateExecutionAgainstContract(document: GraphDocument, execution: unknown, options?: WoroxRuntimeValidationOptions): ValidationResult;
+/**
+ * Validates `finalOutput` against `document.metadata.graphResponse.finalOutputSchema` when present.
+ * If there is no schema, or `graphResponse` is missing, returns `{ valid: true, errors: [] }`.
+ */
+export declare function validateFinalOutputAgainstContract(document: GraphDocument, finalOutput: unknown, options?: WoroxRuntimeValidationOptions): ValidationResult;
+//# sourceMappingURL=validateWorox.d.ts.map

package/dist/validateWorox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateWorox.d.ts","sourceRoot":"","sources":["../src/validateWorox.ts"],"names":[],"mappings":"AAAA,OAAO,GAAgD,MAAM,KAAK,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAyBpE,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAwBlB;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAwBlB"}

package/dist/validateWorox.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateExecutionAgainstContract = validateExecutionAgainstContract;
+exports.validateFinalOutputAgainstContract = validateFinalOutputAgainstContract;
+const ajv_1 = __importDefault(require("ajv"));
+const defaultAjv = new ajv_1.default({
+    allErrors: true,
+    strict: false
+});
+function normalizeError(error) {
+    return {
+        message: error.message ?? "Validation error",
+        path: error.instancePath || error.schemaPath,
+        keyword: error.keyword,
+        params: (error.params ?? {})
+    };
+}
+function runCompiled(validate, data) {
+    const valid = validate(data);
+    if (valid) {
+        return { valid: true, errors: [] };
+    }
+    const errors = (validate.errors ?? []).map(normalizeError);
+    return { valid: false, errors };
+}
+/**
+ * Validates `execution` against `document.metadata.graphEntry.executionSchema` when present.
+ * If there is no schema, or `graphEntry` is missing, returns `{ valid: true, errors: [] }`.
+ * This is optional tooling; graphenix planning does not require it.
+ */
+function validateExecutionAgainstContract(document, execution, options) {
+    const schema = document.metadata?.graphEntry?.executionSchema;
+    if (schema === undefined || schema === null || typeof schema !== "object") {
+        return { valid: true, errors: [] };
+    }
+    const ajv = options?.ajv ?? defaultAjv;
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return {
+            valid: false,
+            errors: [
+                {
+                    message: `Invalid executionSchema: ${message}`,
+                    path: "/metadata/graphEntry/executionSchema",
+                    keyword: "compile",
+                    params: {}
+                }
+            ]
+        };
+    }
+    return runCompiled(validate, execution);
+}
+/**
+ * Validates `finalOutput` against `document.metadata.graphResponse.finalOutputSchema` when present.
+ * If there is no schema, or `graphResponse` is missing, returns `{ valid: true, errors: [] }`.
+ */
+function validateFinalOutputAgainstContract(document, finalOutput, options) {
+    const schema = document.metadata?.graphResponse?.finalOutputSchema;
+    if (schema === undefined || schema === null || typeof schema !== "object") {
+        return { valid: true, errors: [] };
+    }
+    const ajv = options?.ajv ?? defaultAjv;
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return {
+            valid: false,
+            errors: [
+                {
+                    message: `Invalid finalOutputSchema: ${message}`,
+                    path: "/metadata/graphResponse/finalOutputSchema",
+                    keyword: "compile",
+                    params: {}
+                }
+            ]
+        };
+    }
+    return runCompiled(validate, finalOutput);
+}
+//# sourceMappingURL=validateWorox.js.map

package/dist/validateWorox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateWorox.js","sourceRoot":"","sources":["../src/validateWorox.ts"],"names":[],"mappings":"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"}

package/docs/interop-worox-graph.md

@@ -0,0 +1,29 @@
+# Interop: worox-graph JSON and graphenix-format `Graph`
+
+This note clarifies how **worox-graph** graph JSON relates to the **port-based** `Graph` type in graphenix-format. It applies to authors using both `@woroces/worox-graph` and `graphenix-format` validation.
+
+## Two representations
+
+| Area | worox-graph | graphenix-format core `Graph` |
+|------|----------------|--------------------------------|
+| Topology | Task nodes, edges, `outputMapping`, finalizers | Nodes, edges, **ports**, `GraphInput` / `GraphOutput` |
+| Execution shape | Engine-specific (tasks, DAG scheduling) | **Execution-agnostic** static description |
+| I/O contracts | Often embedded in graph JSON and tooling | **Optional** `metadata.graphEntry` / `metadata.graphResponse` on the **document** |
+
+worox-graph focuses on runnable task graphs and visibility into execution paths. graphenix-format describes a **static** graph layout (ports, graph-level inputs/outputs) without prescribing how the runtime schedules tasks.
+
+## Where worox-graph JSON lives
+
+- **Canonical for this package:** optional **`GraphDocument.metadata.graphEntry`** and **`GraphDocument.metadata.graphResponse`** (first-class optional fields). These match the worox contracts used when values are copied to `variables.__graphModel` and keep a single place for validation and docs.
+- **`extensions`:** you may still place namespaced worox-only payloads under `extensions` (e.g. legacy or engine-specific blobs). That does **not** replace `metadata.graphEntry` / `metadata.graphResponse` when you want graphenix-format schema and types to validate the same shapes as worox-graph.
+
+FR-GXF-1 does **not** change graphenix-format’s execution model: the core `Graph` remains port-based.
+
+## DAG nodes vs ports: is there a converter?
+
+**Not in graphenix-format today.** A future **optional** converter could map worox task nodes ↔ port graphs; nothing in the entry/response metadata requires or implies that mapping. Until such a tool exists, treat worox graph JSON and graphenix `Graph` as related **documentation and planning** layers, not automatic transforms of each other.
+
+## See also
+
+- README: **Worox-graph alignment** (I/O layers 01 / 08).
+- `schema/graphenix-format-1.0.0.schema.json`: `$defs/GraphEntryContract`, `$defs/GraphResponseContract`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphenix-format",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Graphenix graph description format: JSON schema, validation, and CRUD helpers.",
   "license": "MIT",
   "main": "dist/index.cjs",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "schema"
+    "schema",
+    "docs"
   ],
   "keywords": [
     "graph",

package/schema/graphenix-format-1.0.0.schema.json

@@ -51,6 +51,19 @@
       "type": "object",
       "description": "Namespaced extension object. Engines that do not recognize an extension namespace must ignore it.",
       "additionalProperties": true
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional document metadata. `graphEntry` and `graphResponse` align with worox-graph graph JSON contracts (I/O layers 01 and 08); other keys are allowed for tooling.",
+      "additionalProperties": true,
+      "properties": {
+        "graphEntry": {
+          "$ref": "#/$defs/GraphEntryContract"
+        },
+        "graphResponse": {
+          "$ref": "#/$defs/GraphResponseContract"
+        }
+      }
     }
   },
   "$defs": {
@@ -432,6 +445,46 @@
           "additionalProperties": true
         }
       }
+    },
+    "GraphEntryContract": {
+      "type": "object",
+      "description": "Worox-graph entry contract: execution inputs and paths (layer 01). Additional properties may be added by worox-graph.",
+      "additionalProperties": true,
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "Human-readable summary of entry expectations."
+        },
+        "requiredExecutionPaths": {
+          "type": "array",
+          "description": "Descriptors for execution paths that must be satisfied (engine-specific item shape).",
+          "items": {}
+        },
+        "executionSchema": {
+          "type": "object",
+          "description": "JSON Schema for the merged execution object (tooling validates at runtime when enabled)."
+        },
+        "notableExecutionPaths": {
+          "type": "array",
+          "description": "Notable optional or diagnostic execution paths.",
+          "items": {}
+        }
+      }
+    },
+    "GraphResponseContract": {
+      "type": "object",
+      "description": "Worox-graph response contract: final output shape (layer 08). Additional properties may be added by worox-graph.",
+      "additionalProperties": true,
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "Human-readable summary of the response / final output."
+        },
+        "finalOutputSchema": {
+          "type": "object",
+          "description": "JSON Schema for the final output value (tooling validates at runtime when enabled)."
+        }
+      }
     }
   }
 }